From 4764d1afcec0fd6b4ae328272ffba6efce597701 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Fri, 25 Sep 2026 16:04:39 +0200 Subject: [PATCH 1/6] chore: adjust shopware-cli tools docs --- products/tools/cli/automatic-refactoring.md | 10 +++-- products/tools/cli/formatter.md | 6 ++- products/tools/cli/index.md | 4 +- products/tools/cli/validation.md | 45 +++++++++------------ 4 files changed, 30 insertions(+), 35 deletions(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index 1809bf4af2..c75069462b 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -34,7 +34,7 @@ Automatic refactoring is one part of an upgrade workflow rather than a complete ## Automatic refactoring tools -Without `--only`, a `fix` command invokes every registered verifier tool. The following tools currently implement changes in `Fix()`: +Without `--only`, a `fix` command invokes every registered fixer. The following tools support fixing: | Tool | What it fixes | Version-aware | Implementation | | ------------- | -------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | @@ -46,15 +46,17 @@ Without `--only`, a `fix` command invokes every registered verifier tool. The fo The Administration Twig migrations are implemented as individual fixers under [`internal/verifier/twiglinter/admintwiglinter`](https://github.com/shopware/shopware-cli/tree/main/internal/verifier/twiglinter/admintwiglinter). They cover deterministic migrations such as replacing removed Administration components. For migration cases that require manual changes, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). -Other registered tools do not modify files in `fix` mode: +Other tools support validation or formatting instead: - `php-cs-fixer` and `prettier` are used for [formatting](./formatter.md). - `phpstan`, `storefront-twig`, and `sw-cli` report findings during [validation](./validation.md). -Selecting one of these tools with `fix --only` therefore does not modify anything. +Selecting one of these tools with `fix --only` is an error; the command lists the available fixers. + +`extension fix` prints a `Fixers:` table after running. `Invoked` means the fixer was called, not that it changed a file; `skipped` means it was not selected by `--only`. `project fix` does not print this table. ::: warning -Rector applies PHP migrations during `fix`, but its `Check()` implementation does not report findings during validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`. +Rector applies PHP migrations during `fix`, but does not support validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`. ::: ## Refactor an extension diff --git a/products/tools/cli/formatter.md b/products/tools/cli/formatter.md index eabd21d314..7c66ba4666 100644 --- a/products/tools/cli/formatter.md +++ b/products/tools/cli/formatter.md @@ -20,7 +20,7 @@ The Docker examples are recommended because the image already contains the requi ## Formatting tools -Without `--only`, a `format` command invokes every registered verifier tool. The following tools currently implement formatting in `Format()`: +Without `--only`, a `format` command invokes every registered formatter. The following tools support formatting: | Tool | What it formats | Implementation | | -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | @@ -28,7 +28,9 @@ Without `--only`, a `format` command invokes every registered verifier tool. The | `prettier` | Prettier-supported files in source directories using the Shopware CLI bundled configuration | [`prettier.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/prettier.go) | | `admin-twig` | Administration Twig templates | [`admin_twig.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/admin_twig.go) | -Other registered verifier tools do not modify files in `format` mode. +Tools without formatting support cannot be selected with `format --only`; the command reports an error and lists the available formatters. + +`extension format` prints a `Formatters:` table after running. `Invoked` means the formatter was called, not that it changed a file; `skipped` means it was not selected by `--only`. `project format` does not print this table. ## Format an extension diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index 22e9c97c54..9d637bb62f 100644 --- a/products/tools/cli/index.md +++ b/products/tools/cli/index.md @@ -23,14 +23,14 @@ Shopware CLI runs on macOS, Linux, and via Docker. For workstation hardware requ ## Verifier tooling requirements -The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run verifier tooling directly on the host — such as `extension validate --full`, `project validate`, `extension fix`, `project fix`, or the format commands — provide: +The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run external verifier tooling directly on the host — such as `extension validate --full`, `extension validate --only phpstan`, `project validate`, the fix commands, or the format commands — provide: - **PHP 8.2.0** or newer - **Node.js 20.0.0** or newer - **Composer** when the CLI prepares PHP verifier dependencies or resolves project/extension dependencies - **npm** when the CLI prepares its JavaScript verifier dependencies -Basic `extension validate` uses the built-in `sw-cli` checks and does not require a local PHP or Node.js runtime. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments. +Basic `extension validate` uses the built-in `sw-cli` checks and does not require a local PHP or Node.js runtime. Selecting only a native Twig checker also skips external tool setup. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments. When you use the Docker-based development environment, run Composer and PHP tools inside the web container rather than on the host. See [Running Composer, PHP, and npm](../../../guides/development/dev-environment.md#running-composer-php-and-npm). diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 78899e1343..a69cc55376 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -16,15 +16,13 @@ Validation has two modes: - **Basic (default)**: Runs the built-in `sw-cli` checks, including metadata, icon, snippets, PHP linting, and packaging-related checks. It does not require a locally installed PHP or Node.js runtime. - **Full (`--full`)**: Runs the basic checks plus validation tools such as PHPStan, ESLint, Stylelint, and the Administration and Storefront Twig linters. -:::warning -`--only` does not enable full validation. Without `--full`, `extension validate` runs only the built-in `sw-cli` checks. For example, `extension validate --only phpstan` does not run PHPStan; use `extension validate --full --only phpstan`. -::: +`--only` selects checkers independently of `--full`. For example, `extension validate /ext --only phpstan` runs PHPStan without the built-in `sw-cli` checks. ### Recommended setup: Docker Run Shopware CLI through the `ghcr.io/shopware/shopware-cli` Docker image for a consistent validation environment without managing the required runtimes on the host. The primary examples on this page use Docker. -If you already run Shopware CLI directly in an existing development or CI environment, the same CLI commands continue to work. For full validation, the host environment must provide PHP 8.2 or newer, Node.js 20 or newer, Composer, and npm. +If you already run Shopware CLI directly in an existing development or CI environment, the same CLI commands continue to work. Full validation, or selecting PHPStan, ESLint, or Stylelint with `--only`, requires PHP 8.2 or newer, Node.js 20 or newer, Composer, and npm on the host. ## Validating an extension @@ -46,10 +44,10 @@ For direct CLI execution, relative paths are resolved from the current working d `extension validate` accepts both a source directory and a built zip file, and the two are not equivalent: -| Input | Behavior | -| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Directory | Intended for feedback during development. `zip.disallowed_file` findings are automatically ignored for directory input. With `--full`, the files are copied to a temporary directory first unless `--no-copy` is used. | -| zip file | Validates the packaged artifact. Packaging-related validation is not automatically suppressed. | +| Input | Behavior | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Directory | Development input. Ignores `zip.disallowed_file`; copied to a temporary directory when PHPStan, ESLint, or Stylelint is selected, unless `--no-copy` is used. | +| Zip file | Validates the packaged artifact. Packaging-related validation is not automatically suppressed. | For day-to-day development, validate the source directory. Before uploading a release, validate the packaged zip so the checks run against the artifact you intend to submit. @@ -99,7 +97,7 @@ If you run Shopware CLI directly on the host, the equivalent command is: shopware-cli extension validate --full /path/to/your/extension ``` -For direct execution, Shopware CLI prepares a cached tool directory for the CLI version. On first use it installs the PHP tool dependencies with Composer and the JavaScript tool dependencies with npm. If the validated extension has no `vendor` directory, full validation also resolves its Composer dependencies; packages listed under `suggest` are included so optional integrations can be analyzed. Private Composer packages require appropriate Composer authentication. +For direct execution with PHPStan, ESLint, or Stylelint selected, Shopware CLI prepares a cached tool directory for the CLI version. On first use it installs the PHP tool dependencies with Composer and the JavaScript tool dependencies with npm. If the validated extension has no `vendor` directory, PHPStan also resolves its Composer dependencies; packages listed under `suggest` are included so optional integrations can be analyzed. Private Composer packages require appropriate Composer authentication. On a clean full-validation run, dependency resolution can take some time. Composer progress is not streamed while this step runs, so the command can remain quiet until dependency resolution completes. @@ -138,14 +136,16 @@ Use `--format` to specify the output format (the older `--reporter` flag is depr If `--format` is not set, the format is detected automatically: `github` in GitHub Actions, `gitlab` in GitLab CI, and `summary` otherwise. +`extension validate` also reports which checkers were `invoked` or `skipped`. `Invoked` means the checker was called, not that it analyzed files or produced findings; a checker can have no applicable files. Summary and GitHub logs show a checker table before the closing summary. Markdown includes the table, JSON includes a `tools` array, and JUnit includes checker test cases. GitLab and JUnit write the human-readable table to stderr so stdout remains machine-readable. If a checker returns an execution error, the report is still emitted and the command fails. + ## Running specific validation tools -With `--full`, `extension validate` calls the validation check implemented by each registered tool. The tools that currently add validation findings are: +With `--full`, `extension validate` calls every registered checker. Without `--full`, it calls `sw-cli` by default, or the checkers named with `--only`. The available tool capabilities are: | Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | | ----------------- | --------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `sw-cli` | ✅ (extensions only) | — | — | Extension metadata, snippets, structure, packaging. Returns immediately for a project, so **projects get no metadata validation** | -| `phpstan` | ✅ | — | — | PHP static analysis; skipped for apps (no `composer.json`) | +| `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | | `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | | `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | | `admin-twig` | ✅ | ✅ | ✅ | Administration Twig component checks and migrations | @@ -155,16 +155,7 @@ With `--full`, `extension validate` calls the validation check implemented by ea | `php-cs-fixer` | — | — | ✅ | PHP code style (Shopware Coding Standard) | | `prettier` | — | — | ✅ | JavaScript, Vue, TypeScript, CSS, SCSS formatting | -Every tool is registered for all three verbs, but the unmarked combinations above are implemented as no-ops. Passing such a tool to `--only` is therefore silently ineffective — `fix --only phpstan` and `fix --only prettier` both do nothing. - -### Which tools each command actually runs - -| Command | Tools that do work | -| ------------------------------------- | --------------------------------------------------------------------------- | -| `extension validate` | `sw-cli`, `phpstan`, `eslint`, `stylelint`, `admin-twig`, `storefront-twig` | -| `project validate` | the same, minus `sw-cli` | -| `extension fix` / `project fix` | `rector`, `admin-twig`, `eslint`, `stylelint`, `symfony-xml` | -| `extension format` / `project format` | `admin-twig`, `php-cs-fixer`, `prettier` | +Each command selects only tools that support its operation. An unsupported `--only` name is an error that lists the available tools for that command; for example, `validate --only prettier` and `fix --only phpstan` are errors. ### Shopware-specific validation rules @@ -179,28 +170,28 @@ Additional plugins enforce accessibility (`eslint-plugin-vuejs-accessibility`), You can run only selected validation tools: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --only phpstan +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext --only phpstan ``` Or run multiple validation tools by separating them with commas: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --only "phpstan,eslint,stylelint" +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext --only "phpstan,eslint,stylelint" ``` If you run Shopware CLI directly, use the same flags with the local extension path. -The inverse is `--exclude`, which runs all registered tools except the listed names: +Use `--exclude` to remove tools from the selected set. With `--full`, that set contains every checker: ```shell docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --exclude "eslint,stylelint" ``` -Both flags accept a comma-separated list and fail with an error if a tool name does not exist. +Both flags accept a comma-separated list. `--only` fails if a name is not a checker; `--exclude` fails if a name is not in the selected set. ### Running without copying the sources -With `--full`, a directory input is copied to a temporary directory before the tools run. Use `--no-copy` to run directly in the mounted source directory instead: +When PHPStan, ESLint, or Stylelint is selected, a directory input is copied to a temporary directory before the tools run. Basic validation and Twig-only checks stay in place. Use `--no-copy` to run directly in the mounted source directory instead: ```shell docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full --no-copy /ext @@ -334,7 +325,7 @@ If you omit the path, `project validate` discovers the nearest Shopware project | `--no-copy` | Analyze the project in place instead of copying it to a temporary directory first | | `--format` | Reporting format (`summary`, `json`, `github`, `gitlab`, `junit`, `markdown`) | -`project validate` has no `--full` flag — it runs its registered validation tools by default. It also has no `--check-against`; that flag exists only on `extension validate`. +`project validate` has no `--full` flag — it runs its registered checkers by default. `sw-cli` is included in that registry but returns immediately without a single-extension context; `--only sw-cli` therefore reports no metadata findings. Use `extension validate` to check an individual extension. `project validate` also has no `--check-against`; that flag exists only on `extension validate`. Use `--local-only` when you want extension discovery limited to the `custom/*` folders: From 62f4eadc659e870540aeb969aab89859d753dd31 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Fri, 25 Sep 2026 16:24:50 +0200 Subject: [PATCH 2/6] chore: document exclude flag for fix and format commands --- products/tools/cli/automatic-refactoring.md | 22 +++++++++++++++------ products/tools/cli/formatter.md | 19 ++++++++++++++++-- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index c75069462b..fa63878d74 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -34,7 +34,7 @@ Automatic refactoring is one part of an upgrade workflow rather than a complete ## Automatic refactoring tools -Without `--only`, a `fix` command invokes every registered fixer. The following tools support fixing: +By default, a `fix` command invokes every registered fixer. The following tools support fixing: | Tool | What it fixes | Version-aware | Implementation | | ------------- | -------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | @@ -53,7 +53,7 @@ Other tools support validation or formatting instead: Selecting one of these tools with `fix --only` is an error; the command lists the available fixers. -`extension fix` prints a `Fixers:` table after running. `Invoked` means the fixer was called, not that it changed a file; `skipped` means it was not selected by `--only`. `project fix` does not print this table. +`extension fix` prints a `Fixers:` table after running. `Invoked` means the fixer was called, not that it changed a file; `skipped` means it was not selected by `--only` or was removed by `--exclude`. `project fix` does not print this table. ::: warning Rector applies PHP migrations during `fix`, but does not support validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`. @@ -98,12 +98,22 @@ shopware-cli extension fix /path/to/your/extension --only rector shopware-cli extension fix /path/to/your/extension --only "rector,eslint,admin-twig" ``` +Use `--exclude` to skip fixers. It removes tools from the set selected by `--only`, or from all fixers when `--only` is omitted: + +```shell +shopware-cli extension fix /path/to/your/extension --exclude eslint +shopware-cli extension fix /path/to/your/extension --only "rector,eslint" --exclude eslint +``` + +Both flags accept comma-separated names. An unknown name, an excluded fixer outside the selected set, or excluding every selected fixer is an error. + Available options: -| Flag | Description | -| ----------------- | ----------------------------------------------------------------------------- | -| `--only ` | Run only the specified comma-separated tools | -| `--allow-non-git` | Allow the command to run when the extension directory is not a Git repository | +| Flag | Description | +| ------------------- | ----------------------------------------------------------------------------- | +| `--only ` | Run only the specified comma-separated tools | +| `--exclude ` | Skip the specified comma-separated fixers after applying `--only` | +| `--allow-non-git` | Allow the command to run when the extension directory is not a Git repository | For `extension fix`, the extension directory itself must contain `.git`; being inside a parent Git-managed Shopware project is not sufficient. Use `--allow-non-git` when you intentionally want to fix such an extension. `project fix` checks the project root instead. diff --git a/products/tools/cli/formatter.md b/products/tools/cli/formatter.md index 7c66ba4666..48d9518d0e 100644 --- a/products/tools/cli/formatter.md +++ b/products/tools/cli/formatter.md @@ -20,7 +20,7 @@ The Docker examples are recommended because the image already contains the requi ## Formatting tools -Without `--only`, a `format` command invokes every registered formatter. The following tools support formatting: +By default, a `format` command invokes every registered formatter. The following tools support formatting: | Tool | What it formats | Implementation | | -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | @@ -30,7 +30,7 @@ Without `--only`, a `format` command invokes every registered formatter. The fol Tools without formatting support cannot be selected with `format --only`; the command reports an error and lists the available formatters. -`extension format` prints a `Formatters:` table after running. `Invoked` means the formatter was called, not that it changed a file; `skipped` means it was not selected by `--only`. `project format` does not print this table. +`extension format` prints a `Formatters:` table after running. `Invoked` means the formatter was called, not that it changed a file; `skipped` means it was not selected by `--only` or was removed by `--exclude`. `project format` does not print this table. ## Format an extension @@ -72,6 +72,21 @@ shopware-cli extension format /path/to/your/extension --dry-run The extension path is required. +Use `--exclude` to skip formatters. It removes tools from the set selected by `--only`, or from all formatters when `--only` is omitted: + +```shell +shopware-cli extension format /path/to/your/extension --exclude prettier +shopware-cli extension format /path/to/your/extension --only "prettier,php-cs-fixer" --exclude prettier +``` + +Both flags accept comma-separated names. An unknown name, an excluded formatter outside the selected set, or excluding every selected formatter is an error. + +| Flag | Description | +| ------------------- | -------------------------------------------------------------- | +| `--only ` | Run only the specified comma-separated formatters | +| `--exclude ` | Skip the specified comma-separated formatters after `--only` | +| `--dry-run` | Check formatting without modifying files | + ## Format a project From c23f83e35ae7bbdbbd01d484ef1ca0757a3432a3 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Wed, 30 Sep 2026 15:59:21 +0200 Subject: [PATCH 3/6] chore: adjust to breaking changes --- products/tools/cli/automatic-refactoring.md | 2 +- products/tools/cli/index.md | 4 +- products/tools/cli/validation.md | 60 ++++++++++----------- 3 files changed, 33 insertions(+), 33 deletions(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index fa63878d74..b0fdd1ca25 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -49,7 +49,7 @@ The Administration Twig migrations are implemented as individual fixers under [` Other tools support validation or formatting instead: - `php-cs-fixer` and `prettier` are used for [formatting](./formatter.md). -- `phpstan`, `storefront-twig`, and `sw-cli` report findings during [validation](./validation.md). +- `phpstan`, `storefront-twig`, and `builtin` report findings during [validation](./validation.md). The legacy `sw-cli` name remains accepted as an input alias. Selecting one of these tools with `fix --only` is an error; the command lists the available fixers. diff --git a/products/tools/cli/index.md b/products/tools/cli/index.md index 9d637bb62f..b6d56ca263 100644 --- a/products/tools/cli/index.md +++ b/products/tools/cli/index.md @@ -23,14 +23,14 @@ Shopware CLI runs on macOS, Linux, and via Docker. For workstation hardware requ ## Verifier tooling requirements -The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run external verifier tooling directly on the host — such as `extension validate --full`, `extension validate --only phpstan`, `project validate`, the fix commands, or the format commands — provide: +The Shopware CLI binary itself does not require PHP or Node.js for every command. When you run external verifier tooling directly on the host — such as `extension validate`, `extension validate --only phpstan`, `project validate`, the fix commands, or the format commands — provide: - **PHP 8.2.0** or newer - **Node.js 20.0.0** or newer - **Composer** when the CLI prepares PHP verifier dependencies or resolves project/extension dependencies - **npm** when the CLI prepares its JavaScript verifier dependencies -Basic `extension validate` uses the built-in `sw-cli` checks and does not require a local PHP or Node.js runtime. Selecting only a native Twig checker also skips external tool setup. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments. +`extension validate --only builtin` uses the built-in checks and does not require a local PHP or Node.js runtime. The legacy alias `sw-cli` remains accepted. Selecting only a native Twig checker also skips external tool setup. The [Docker images](installation.md#docker-image) include the verifier runtime dependencies and are recommended for consistent validation, refactoring, and formatting environments. When you use the Docker-based development environment, run Composer and PHP tools inside the web container rather than on the host. See [Running Composer, PHP, and npm](../../../guides/development/dev-environment.md#running-composer-php-and-npm). diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index a69cc55376..3078eae283 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -11,18 +11,18 @@ Shopware CLI has built-in validation for extensions. Run it during development a Validation covers technical criteria that can be automated, such as metadata, packaging, static analysis, and linting. It is not a one-to-one replica of the complete Shopware Store review, which also includes functional testing, Store page content, and manual review. A successful validation run is a strong technical pre-upload signal, but it does not guarantee Store approval or mean that the CLI and Store review use an identical rule set. -Validation has two modes: +By default, `extension validate` runs every checker: -- **Basic (default)**: Runs the built-in `sw-cli` checks, including metadata, icon, snippets, PHP linting, and packaging-related checks. It does not require a locally installed PHP or Node.js runtime. -- **Full (`--full`)**: Runs the basic checks plus validation tools such as PHPStan, ESLint, Stylelint, and the Administration and Storefront Twig linters. +- The built-in `builtin` checks cover metadata, icon, snippets, PHP linting, and packaging-related checks. The legacy name `sw-cli` remains accepted as an input alias. +- PHPStan, ESLint, Stylelint, and the Administration and Storefront Twig linters provide additional checks. -`--only` selects checkers independently of `--full`. For example, `extension validate /ext --only phpstan` runs PHPStan without the built-in `sw-cli` checks. +Use `--only` to select specific checkers. For example, `extension validate /ext --only phpstan` runs PHPStan without the built-in `builtin` checks. To run only the built-in checks, use `--only builtin`; `--only sw-cli` remains supported for backwards compatibility and emits a deprecation warning. The deprecated `--full` flag is still accepted, but has no effect because all checkers run by default. ### Recommended setup: Docker Run Shopware CLI through the `ghcr.io/shopware/shopware-cli` Docker image for a consistent validation environment without managing the required runtimes on the host. The primary examples on this page use Docker. -If you already run Shopware CLI directly in an existing development or CI environment, the same CLI commands continue to work. Full validation, or selecting PHPStan, ESLint, or Stylelint with `--only`, requires PHP 8.2 or newer, Node.js 20 or newer, Composer, and npm on the host. +If you already run Shopware CLI directly in an existing development or CI environment, the same CLI commands continue to work. Default validation, or selecting PHPStan, ESLint, or Stylelint with `--only`, requires PHP 8.2 or newer, Node.js 20 or newer, Composer, and npm on the host. ## Validating an extension @@ -51,9 +51,9 @@ For direct CLI execution, relative paths are resolved from the current working d For day-to-day development, validate the source directory. Before uploading a release, validate the packaged zip so the checks run against the artifact you intend to submit. -## What is validated in basic mode? +## What does the built-in checker validate? -Basic mode runs the `sw-cli` tool. It includes checks such as the following; this list is not exhaustive. The identifier in brackets is the value you can use in [validation ignores](#validation-ignores). +The built-in `builtin` checker is included by default and can be run alone with `--only builtin` (`--only sw-cli` remains a backwards-compatible alias). It includes checks such as the following; this list is not exhaustive. The identifier in brackets is the value you can use in [validation ignores](#validation-ignores). Metadata and extension structure checks include: @@ -72,7 +72,7 @@ Zip validation also runs packaging-related checks that are suppressed for direct ### Supported PHP versions for linting -Shopware CLI uses an embedded Go-based PHP linter. It does not download or execute PHP runtimes for basic PHP linting. +Shopware CLI uses an embedded Go-based PHP linter. It does not download or execute PHP runtimes for the built-in PHP linting check. 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. @@ -83,36 +83,36 @@ validation: php_version: '8.4' ``` -## Running full validation +## Running all checkers -Use `--full` to add the additional validation tools to the built-in checks: +All checkers run by default: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext ``` If you run Shopware CLI directly on the host, the equivalent command is: ```shell -shopware-cli extension validate --full /path/to/your/extension +shopware-cli extension validate /path/to/your/extension ``` For direct execution with PHPStan, ESLint, or Stylelint selected, Shopware CLI prepares a cached tool directory for the CLI version. On first use it installs the PHP tool dependencies with Composer and the JavaScript tool dependencies with npm. If the validated extension has no `vendor` directory, PHPStan also resolves its Composer dependencies; packages listed under `suggest` are included so optional integrations can be analyzed. Private Composer packages require appropriate Composer authentication. -On a clean full-validation run, dependency resolution can take some time. Composer progress is not streamed while this step runs, so the command can remain quiet until dependency resolution completes. +On a clean validation run, dependency resolution can take some time. Composer progress is not streamed while this step runs, so the command can remain quiet until dependency resolution completes. `--check-against` controls Composer dependency resolution within the extension's declared constraints; it is not an arbitrary target-version selector. By default, Composer dependency resolution uses the highest versions allowed by the extension constraints. To test the other end of the supported range, use `--check-against lowest`: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --check-against lowest -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --check-against highest +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext --check-against lowest +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext --check-against highest ``` If you run Shopware CLI directly: ```shell -shopware-cli extension validate --full /path/to/your/extension --check-against lowest -shopware-cli extension validate --full /path/to/your/extension --check-against highest +shopware-cli extension validate /path/to/your/extension --check-against lowest +shopware-cli extension validate /path/to/your/extension --check-against highest ``` With `--check-against lowest`, Composer adds `--prefer-lowest` when it resolves the extension dependencies. @@ -140,11 +140,11 @@ If `--format` is not set, the format is detected automatically: `github` in GitH ## Running specific validation tools -With `--full`, `extension validate` calls every registered checker. Without `--full`, it calls `sw-cli` by default, or the checkers named with `--only`. The available tool capabilities are: +By default, `extension validate` calls every registered checker. Use `--only` or `--exclude` to narrow the selection. The available tool capabilities are: | Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | | ----------------- | --------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `sw-cli` | ✅ (extensions only) | — | — | Extension metadata, snippets, structure, packaging. Returns immediately for a project, so **projects get no metadata validation** | +| `builtin` | ✅ (extensions only) | — | — | Extension metadata, snippets, structure, packaging. `sw-cli` is accepted as a legacy alias. Returns immediately for a project, so **projects get no metadata validation** | | `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | | `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | | `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | @@ -181,10 +181,10 @@ docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validat If you run Shopware CLI directly, use the same flags with the local extension path. -Use `--exclude` to remove tools from the selected set. With `--full`, that set contains every checker: +Use `--exclude` to remove tools from the selected set. Without `--only`, that set contains every checker: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --exclude "eslint,stylelint" +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext --exclude "eslint,stylelint" ``` Both flags accept a comma-separated list. `--only` fails if a name is not a checker; `--exclude` fails if a name is not in the selected set. @@ -194,20 +194,20 @@ Both flags accept a comma-separated list. `--only` fails if a name is not a chec When PHPStan, ESLint, or Stylelint is selected, a directory input is copied to a temporary directory before the tools run. Basic validation and Twig-only checks stay in place. Use `--no-copy` to run directly in the mounted source directory instead: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full --no-copy /ext +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --no-copy /ext ``` For direct CLI execution, the equivalent option is: ```shell -shopware-cli extension validate --full --no-copy /path/to/your/extension +shopware-cli extension validate --no-copy /path/to/your/extension ``` This can be faster on large extensions and keeps generated dependency or cache files, such as `vendor/` and `composer.lock`, in the source directory, but it also means validation tools can modify or add files there. ## Checking a release before uploading it to the Store -For the strongest pre-upload signal available from Shopware CLI, validate the same package that you intend to upload with `--full`. This runs the full validator set used by the CLI against the packaged artifact. It does not guarantee that every Store-review criterion is represented in the CLI or that passing validation guarantees Store approval. +For the strongest pre-upload signal available from Shopware CLI, validate the same package that you intend to upload. This runs the full validator set used by the CLI against the packaged artifact. It does not guarantee that every Store-review criterion is represented in the CLI or that passing validation guarantees Store approval. `extension package` is the current packaging command. `extension zip` remains available as a deprecated alias. @@ -221,14 +221,14 @@ docker run --rm -v "$(pwd)":/ext -w /ext ghcr.io/shopware/shopware-cli extension Then validate the packaged artifact: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext/dist/extension.zip +docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate /ext/dist/extension.zip ``` If you already run Shopware CLI directly, the corresponding workflow is: ```shell shopware-cli extension package /path/to/your/extension --release --output-directory dist --filename extension.zip -shopware-cli extension validate --full dist/extension.zip +shopware-cli extension validate dist/extension.zip ``` See [Building Extensions and Creating Archives](./extension-commands/build.md) for packaging options and [Releasing an extension to the Shopware Store](./shopware-account-commands/releasing-extension-to-shopware-store.md) for the upload itself. @@ -245,7 +245,7 @@ jobs: steps: - uses: actions/checkout@v4 - name: Validate extension - run: docker run --rm -v "$GITHUB_WORKSPACE":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext + run: docker run --rm -v "$GITHUB_WORKSPACE":/ext ghcr.io/shopware/shopware-cli extension validate /ext validate-release: if: startsWith(github.ref, 'refs/tags/') @@ -257,7 +257,7 @@ jobs: mkdir -p dist docker run --rm -v "$GITHUB_WORKSPACE":/ext -w /ext ghcr.io/shopware/shopware-cli extension package /ext --release --output-directory /ext/dist --filename extension.zip - name: Validate release package - run: docker run --rm -v "$GITHUB_WORKSPACE":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext/dist/extension.zip + run: docker run --rm -v "$GITHUB_WORKSPACE":/ext ghcr.io/shopware/shopware-cli extension validate /ext/dist/extension.zip ``` The `github` format is selected automatically in GitHub Actions, so findings are emitted as GitHub annotations. @@ -310,7 +310,7 @@ 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 `.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. +`project validate` does not run extension metadata and packaging validation for every contained extension. The `builtin` 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. ::: If you omit the path, `project validate` discovers the nearest Shopware project by walking up from the current directory. A directory is recognized when its Composer metadata references `shopware/core` and `bin/console` exists; `PROJECT_ROOT` overrides this discovery. @@ -325,7 +325,7 @@ If you omit the path, `project validate` discovers the nearest Shopware project | `--no-copy` | Analyze the project in place instead of copying it to a temporary directory first | | `--format` | Reporting format (`summary`, `json`, `github`, `gitlab`, `junit`, `markdown`) | -`project validate` has no `--full` flag — it runs its registered checkers by default. `sw-cli` is included in that registry but returns immediately without a single-extension context; `--only sw-cli` therefore reports no metadata findings. Use `extension validate` to check an individual extension. `project validate` also has no `--check-against`; that flag exists only on `extension validate`. +`project validate` also runs its registered checkers by default. It has no `--full` flag. `builtin` is included in that registry but returns immediately without a single-extension context; `--only builtin` therefore reports no metadata findings. The legacy `--only sw-cli` alias is also accepted. Use `extension validate` to check an individual extension. `project validate` also has no `--check-against`; that flag exists only on `extension validate`. Use `--local-only` when you want extension discovery limited to the `custom/*` folders: From 544e6453596e3f6bcff086916ead7dcf8e79eb5b Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Wed, 30 Sep 2026 16:36:38 +0200 Subject: [PATCH 4/6] chore: cleanup --- products/tools/cli/automatic-refactoring.md | 2 +- products/tools/cli/formatter.md | 7 +++ .../cli/project-commands/helper-commands.md | 2 +- products/tools/cli/validation.md | 44 +++++++++++++------ 4 files changed, 40 insertions(+), 15 deletions(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index b0fdd1ca25..f75c85d66b 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -49,7 +49,7 @@ The Administration Twig migrations are implemented as individual fixers under [` Other tools support validation or formatting instead: - `php-cs-fixer` and `prettier` are used for [formatting](./formatter.md). -- `phpstan`, `storefront-twig`, and `builtin` report findings during [validation](./validation.md). The legacy `sw-cli` name remains accepted as an input alias. +- `phpstan`, `storefront-twig`, and `builtin` report findings during [validation](./validation.md). Selecting one of these tools with `fix --only` is an error; the command lists the available fixers. diff --git a/products/tools/cli/formatter.md b/products/tools/cli/formatter.md index 48d9518d0e..a467f68038 100644 --- a/products/tools/cli/formatter.md +++ b/products/tools/cli/formatter.md @@ -72,6 +72,13 @@ shopware-cli extension format /path/to/your/extension --dry-run The extension path is required. +Use `--only` to select one or more formatters: + +```shell +shopware-cli extension format /path/to/your/extension --only php-cs-fixer +shopware-cli extension format /path/to/your/extension --only "php-cs-fixer,admin-twig" +``` + Use `--exclude` to skip formatters. It removes tools from the set selected by `--only`, or from all formatters when `--only` is omitted: ```shell diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 14ad1cd8b4..f1141ca7c2 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -197,7 +197,7 @@ shopware-cli project validate --no-copy shopware-cli project validate --local-only ``` -`--only` and `--exclude` accept comma-separated tool names. +`--only` and `--exclude` accept comma-separated checker names. `--exclude` removes checkers after applying `--only`; names outside the selected set are errors. Tools without validation support, such as `prettier` or `rector`, cannot be selected. The built-in checker is named `builtin`; the legacy `sw-cli` alias is accepted with a deprecation warning. It only checks individual extensions, so use `extension validate` for metadata and packaging checks. See [Validation](../validation.md) for the available validation tools. diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 3078eae283..51e675b6e0 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -18,6 +18,14 @@ By default, `extension validate` runs every checker: Use `--only` to select specific checkers. For example, `extension validate /ext --only phpstan` runs PHPStan without the built-in `builtin` checks. To run only the built-in checks, use `--only builtin`; `--only sw-cli` remains supported for backwards compatibility and emits a deprecation warning. The deprecated `--full` flag is still accepted, but has no effect because all checkers run by default. +Existing scripts and CI jobs that previously omitted `--full` now also run PHPStan, ESLint, Stylelint, and the Twig checkers. They can report additional findings and require external runtime dependencies. To preserve the previous default, select the built-in checker explicitly: + +```shell +shopware-cli extension validate /path/to/your/extension --only builtin +``` + +The legacy name `sw-cli` is accepted in both `--only` and `--exclude` for extension and project validation, with a deprecation warning. Use `builtin` in new configurations. Reports, tool statuses, and selection errors use the canonical name `builtin`. + ### Recommended setup: Docker Run Shopware CLI through the `ghcr.io/shopware/shopware-cli` Docker image for a consistent validation environment without managing the required runtimes on the host. The primary examples on this page use Docker. @@ -142,18 +150,18 @@ If `--format` is not set, the format is detected automatically: `github` in GitH By default, `extension validate` calls every registered checker. Use `--only` or `--exclude` to narrow the selection. The available tool capabilities are: -| Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | -| ----------------- | --------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | +| ----------------- | --------------------- | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `builtin` | ✅ (extensions only) | — | — | Extension metadata, snippets, structure, packaging. `sw-cli` is accepted as a legacy alias. Returns immediately for a project, so **projects get no metadata validation** | -| `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | -| `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | -| `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | -| `admin-twig` | ✅ | ✅ | ✅ | Administration Twig component checks and migrations | -| `storefront-twig` | ✅ | — | — | Storefront Twig checks (accessibility, inline styles); reports only | -| `rector` | — | ✅ | — | PHP breaking-change and upgrade rules. **Rewrites without reporting** — nothing appears in `validate` | -| `symfony-xml` | — | ✅ | — | Converts deprecated `services.xml` / `routes.xml` to YAML | -| `php-cs-fixer` | — | — | ✅ | PHP code style (Shopware Coding Standard) | -| `prettier` | — | — | ✅ | JavaScript, Vue, TypeScript, CSS, SCSS formatting | +| `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | +| `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | +| `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | +| `admin-twig` | ✅ | ✅ | ✅ | Administration Twig component checks and migrations | +| `storefront-twig` | ✅ | — | — | Storefront Twig checks (accessibility, inline styles); reports only | +| `rector` | — | ✅ | — | PHP breaking-change and upgrade rules. **Rewrites without reporting** — nothing appears in `validate` | +| `symfony-xml` | — | ✅ | — | Converts deprecated `services.xml` / `routes.xml` to YAML | +| `php-cs-fixer` | — | — | ✅ | PHP code style (Shopware Coding Standard) | +| `prettier` | — | — | ✅ | JavaScript, Vue, TypeScript, CSS, SCSS formatting | Each command selects only tools that support its operation. An unsupported `--only` name is an error that lists the available tools for that command; for example, `validate --only prettier` and `fix --only phpstan` are errors. @@ -189,9 +197,17 @@ docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validat Both flags accept a comma-separated list. `--only` fails if a name is not a checker; `--exclude` fails if a name is not in the selected set. +When combined, `--only` selects the checkers first and `--exclude` removes checkers from that selection: + +```shell +shopware-cli extension validate /path/to/your/extension --only "builtin,phpstan,eslint" --exclude eslint +``` + +This runs only `builtin` and `phpstan`. Excluding every selected checker is an error for `extension validate`. + ### Running without copying the sources -When PHPStan, ESLint, or Stylelint is selected, a directory input is copied to a temporary directory before the tools run. Basic validation and Twig-only checks stay in place. Use `--no-copy` to run directly in the mounted source directory instead: +When PHPStan, ESLint, or Stylelint is selected, a directory input is copied to a temporary directory before the tools run. Selecting only `builtin` and/or Twig checkers skips copying and external tool setup. Use `--no-copy` to run directly in the mounted source directory instead: ```shell docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --no-copy /ext @@ -321,12 +337,14 @@ If you omit the path, `project validate` discovers the nearest Shopware project | ------------------- | --------------------------------------------------------------------------------- | | `--local-only` | Only discover extensions from `custom/*` folders | | `--only ` | Run only selected tools (comma-separated) | -| `--exclude ` | Run all tools except the listed ones | +| `--exclude ` | Remove the listed checkers from the selection after applying `--only` | | `--no-copy` | Analyze the project in place instead of copying it to a temporary directory first | | `--format` | Reporting format (`summary`, `json`, `github`, `gitlab`, `junit`, `markdown`) | `project validate` also runs its registered checkers by default. It has no `--full` flag. `builtin` is included in that registry but returns immediately without a single-extension context; `--only builtin` therefore reports no metadata findings. The legacy `--only sw-cli` alias is also accepted. Use `extension validate` to check an individual extension. `project validate` also has no `--check-against`; that flag exists only on `extension validate`. +Project validation uses the same checker names and applies `--exclude` after `--only`, rejecting names outside the selected set. It does not include checker invocation statuses in its reports. Unlike extension validation, it initializes external tooling even when only native checkers are selected. + Use `--local-only` when you want extension discovery limited to the `custom/*` folders: ```shell From 5501d6c8d745980e4d45c039ea88b04ac06787de Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Tue, 6 Oct 2026 17:03:10 +0200 Subject: [PATCH 5/6] chore: adjustments based on project command changes --- products/tools/cli/automatic-refactoring.md | 23 +++++++----- products/tools/cli/formatter.md | 31 ++++++++++------ .../cli/project-commands/helper-commands.md | 4 ++- products/tools/cli/validation.md | 35 ++++++++++++------- 4 files changed, 60 insertions(+), 33 deletions(-) diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index f75c85d66b..e502767bce 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -40,11 +40,10 @@ By default, a `fix` command invokes every registered fixer. The following tools | ------------- | -------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | | `rector` | PHP breaking changes and modernization using Shopware Rector | Yes | [`rector.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/rector.go) | | `eslint` | Auto-fixable JavaScript, TypeScript, and Vue rules for Administration and Storefront code | Yes | [`eslint.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/eslint.go) | -| `admin-twig` | Shopware-specific Administration Twig component migrations | Yes | [`admin_twig.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/admin_twig.go) | | `stylelint` | Auto-fixable Administration and Storefront SCSS rules using bundled Stylelint configurations | No | [`stylelint.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/stylelint.go) | | `symfony-xml` | Deprecated plugin `services.xml` and `routes.xml` configuration to YAML | No | [`symfony_xml.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/symfony_xml.go) | -The Administration Twig migrations are implemented as individual fixers under [`internal/verifier/twiglinter/admintwiglinter`](https://github.com/shopware/shopware-cli/tree/main/internal/verifier/twiglinter/admintwiglinter). They cover deterministic migrations such as replacing removed Administration components. For migration cases that require manual changes, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). +For Administration migrations, see the [Administration migration guide](../../../guides/upgrades-migrations/administration/index.md). Other tools support validation or formatting instead: @@ -53,7 +52,7 @@ Other tools support validation or formatting instead: Selecting one of these tools with `fix --only` is an error; the command lists the available fixers. -`extension fix` prints a `Fixers:` table after running. `Invoked` means the fixer was called, not that it changed a file; `skipped` means it was not selected by `--only` or was removed by `--exclude`. `project fix` does not print this table. +`extension fix` and `project fix` print a `Fixers:` table after running. `invoked` means the fixer was called, but does not guarantee that it analyzed or changed files; `skipped` means it was not selected by `--only` or was removed by `--exclude`. The table is also printed when a fixer returns an execution error, and the command exits with a non-zero status. ::: warning Rector applies PHP migrations during `fix`, but does not support validation. There is no Rector preview before files are rewritten, so always review the resulting `git diff`. @@ -95,7 +94,7 @@ Use `--only` to run one or more specific fixers: ```shell shopware-cli extension fix /path/to/your/extension --only rector -shopware-cli extension fix /path/to/your/extension --only "rector,eslint,admin-twig" +shopware-cli extension fix /path/to/your/extension --only "rector,eslint" ``` Use `--exclude` to skip fixers. It removes tools from the set selected by `--only`, or from all fixers when `--only` is omitted: @@ -112,7 +111,7 @@ Available options: | Flag | Description | | ------------------- | ----------------------------------------------------------------------------- | | `--only ` | Run only the specified comma-separated tools | -| `--exclude ` | Skip the specified comma-separated fixers after applying `--only` | +| `--exclude ` | Exclude fixers from all fixers or the `--only` selection | | `--allow-non-git` | Allow the command to run when the extension directory is not a Git repository | For `extension fix`, the extension directory itself must contain `.git`; being inside a parent Git-managed Shopware project is not sufficient. Use `--allow-non-git` when you intentionally want to fix such an extension. `project fix` checks the project root instead. @@ -147,18 +146,22 @@ The project path is optional. If you omit it, Shopware CLI searches upward from shopware-cli project fix ``` -For projects, Shopware CLI applies the selected fixers to local extensions and configured bundles. Extensions resolved under `vendor/` are skipped. Individual fixers can have a narrower scope; for example, `symfony-xml` only converts configuration belonging to platform plugins. +For projects, Shopware CLI applies the selected fixers to local extensions and configured bundles. Extensions resolved under `vendor/` and extensions listed in `validation.ignore_extensions` are skipped. Individual fixers can have a narrower scope; for example, `symfony-xml` only converts configuration belonging to platform plugins. -Use the same `--only` and `--allow-non-git` options as `extension fix`: +Use the same `--only`, `--exclude`, and `--allow-non-git` options as `extension fix`: ```shell shopware-cli project fix --only rector -shopware-cli project fix --only "rector,eslint,admin-twig" +shopware-cli project fix --only "rector,eslint" +shopware-cli project fix --exclude eslint +shopware-cli project fix --only "rector,eslint" --exclude eslint ``` +Without `--only`, exclusions apply to all registered fixers. When both flags are supplied, exclusions apply to the selected set. Unknown names, exclusions outside that set, and empty final selections fail before tool setup or file changes. + ## Version-aware fixes -Some fixers select rules according to the Shopware version supported by the extension or project. `rector`, `eslint`, and `admin-twig` use the minimum Shopware version resolved by the verifier configuration. Stylelint and `symfony-xml` do not select rules based on a Shopware version. +Some fixers select rules according to the Shopware version supported by the extension or project. `rector` and `eslint` use the minimum Shopware version resolved by the verifier configuration. Stylelint and `symfony-xml` do not select rules based on a Shopware version. For a Shopware project, the version range comes from the `shopware/core` constraint in `composer.json`. For an extension, it comes from the extension's declared Shopware compatibility. Shopware CLI retrieves the available Shopware releases and selects the **lowest released version matching that constraint**. @@ -189,6 +192,8 @@ The version-resolution logic is implemented in [`internal/verifier/extension.go` ## Execution and safety +Use `--verbose` with either `fix` command to log source directories, selected extension names, and external tool commands and arguments. + The selected tools run concurrently, and the command waits for them to finish before returning. If one tool fails, the others are not cancelled and may still write changes. A failed run can therefore leave partial modifications. The `fix` commands also: diff --git a/products/tools/cli/formatter.md b/products/tools/cli/formatter.md index a467f68038..18ac147bbc 100644 --- a/products/tools/cli/formatter.md +++ b/products/tools/cli/formatter.md @@ -12,7 +12,7 @@ Shopware CLI provides code formatting through two `format` commands: - `extension format` to format a single extension - `project format` to format extensions and configured bundles across a Shopware project -The formatter covers PHP and Administration Twig files, along with files supported by Prettier such as JavaScript, TypeScript, Vue, CSS, and SCSS. PHP formatting uses the Shopware [Coding Standard](https://developer.shopware.com/docs/resources/guidelines/code/). +The formatter covers PHP files, along with files supported by Prettier such as JavaScript, TypeScript, Vue, CSS, and SCSS. PHP formatting uses the Shopware [Coding Standard](https://developer.shopware.com/docs/resources/guidelines/code/). A `--dry-run` mode is available to check formatting without rewriting the target files. Shopware CLI propagates the formatter exit status, so a non-zero dry run can mean that formatting changes are required rather than that the formatter crashed. @@ -26,11 +26,10 @@ By default, a `format` command invokes every registered formatter. The following | -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `php-cs-fixer` | PHP source files using the Shopware Coding Standard | [`phpcsfixer.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/phpcsfixer.go) | | `prettier` | Prettier-supported files in source directories using the Shopware CLI bundled configuration | [`prettier.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/prettier.go) | -| `admin-twig` | Administration Twig templates | [`admin_twig.go`](https://github.com/shopware/shopware-cli/blob/main/internal/verifier/admin_twig.go) | Tools without formatting support cannot be selected with `format --only`; the command reports an error and lists the available formatters. -`extension format` prints a `Formatters:` table after running. `Invoked` means the formatter was called, not that it changed a file; `skipped` means it was not selected by `--only` or was removed by `--exclude`. `project format` does not print this table. +`extension format` and `project format` print a `Formatters:` table after running. `invoked` means the formatter was called, but does not guarantee that it analyzed or changed files; `skipped` means it was not selected by `--only` or was removed by `--exclude`. The table is also printed when a formatter returns an execution error, and the command exits with a non-zero status. ## Format an extension @@ -76,7 +75,7 @@ Use `--only` to select one or more formatters: ```shell shopware-cli extension format /path/to/your/extension --only php-cs-fixer -shopware-cli extension format /path/to/your/extension --only "php-cs-fixer,admin-twig" +shopware-cli extension format /path/to/your/extension --only "php-cs-fixer,prettier" ``` Use `--exclude` to skip formatters. It removes tools from the set selected by `--only`, or from all formatters when `--only` is omitted: @@ -88,10 +87,12 @@ shopware-cli extension format /path/to/your/extension --only "prettier,php-cs-fi Both flags accept comma-separated names. An unknown name, an excluded formatter outside the selected set, or excluding every selected formatter is an error. +The following table summarizes the extension format options: + | Flag | Description | | ------------------- | -------------------------------------------------------------- | | `--only ` | Run only the specified comma-separated formatters | -| `--exclude ` | Skip the specified comma-separated formatters after `--only` | +| `--exclude ` | Exclude formatters from all formatters or the `--only` selection | | `--dry-run` | Check formatting without modifying files | ## Format a project @@ -140,10 +141,11 @@ If you omit the path, `project format` discovers the nearest Shopware project by ### Project format options -| Flag | Description | -| ---------------- | -------------------------------------------- | -| `--dry-run` | Check formatting without modifying files | -| `--only ` | Run only the specified comma-separated tools | +| Flag | Description | +| ------------------- | --------------------------------------------------------------- | +| `--dry-run` | Check formatting without modifying files | +| `--only ` | Run only the specified comma-separated formatters | +| `--exclude ` | Exclude formatters from all formatters or the `--only` selection | The path argument is optional for `project format` but required for `extension format`. @@ -153,10 +155,17 @@ Format only PHP: shopware-cli project format /path/to/your/project --only php-cs-fixer ``` +Use `--exclude` alone or with `--only`: + +```shell +shopware-cli project format /path/to/your/project --exclude prettier +shopware-cli project format /path/to/your/project --only "prettier,php-cs-fixer" --exclude prettier +``` + +Unknown names, exclusions outside the selected set, and empty final selections fail before tool setup or file changes. Use `--verbose` with either `format` command to log source directories, extension names, and external tool commands and arguments. + ## Configuration PHP-CS-Fixer uses a `.php-cs-fixer.dist.php` from the target root when one is present. Otherwise, Shopware CLI uses its bundled PHP-CS-Fixer configuration. Prettier uses the configuration bundled with Shopware CLI. A project or extension `.prettierrc` is not used by the `format` commands. - -Administration Twig formatting uses the Shopware CLI built-in formatter and has no separate configuration file. diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index f1141ca7c2..20069785ea 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -197,7 +197,9 @@ shopware-cli project validate --no-copy shopware-cli project validate --local-only ``` -`--only` and `--exclude` accept comma-separated checker names. `--exclude` removes checkers after applying `--only`; names outside the selected set are errors. Tools without validation support, such as `prettier` or `rector`, cannot be selected. The built-in checker is named `builtin`; the legacy `sw-cli` alias is accepted with a deprecation warning. It only checks individual extensions, so use `extension validate` for metadata and packaging checks. +`--only` and `--exclude` accept comma-separated checker names. Without `--only`, exclusions apply to all checkers; when both flags are supplied, exclusions apply to the selected set. Unknown names, exclusions outside that set, and empty final selections fail before tool setup or copying. Tools without validation support, such as `prettier` or `rector`, cannot be selected. + +The built-in checker, `builtin`, runs metadata and structure checks for each eligible extension, applying its own validation ignores. Use `--only builtin` to run these checks alone. The legacy `sw-cli` alias is accepted with a deprecation warning. Reports include checker invocation statuses; `invoked` means the checker was called, but does not guarantee that it analyzed files or produced findings. Use `--verbose` to see source directories, extension names, and external tool commands and arguments. See [Validation](../validation.md) for the available validation tools. diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 51e675b6e0..1d4cf0c7d9 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -14,7 +14,7 @@ Validation covers technical criteria that can be automated, such as metadata, pa By default, `extension validate` runs every checker: - The built-in `builtin` checks cover metadata, icon, snippets, PHP linting, and packaging-related checks. The legacy name `sw-cli` remains accepted as an input alias. -- PHPStan, ESLint, Stylelint, and the Administration and Storefront Twig linters provide additional checks. +- PHPStan, ESLint, Stylelint, and the Storefront Twig linter provide additional checks. Use `--only` to select specific checkers. For example, `extension validate /ext --only phpstan` runs PHPStan without the built-in `builtin` checks. To run only the built-in checks, use `--only builtin`; `--only sw-cli` remains supported for backwards compatibility and emits a deprecation warning. The deprecated `--full` flag is still accepted, but has no effect because all checkers run by default. @@ -26,6 +26,8 @@ shopware-cli extension validate /path/to/your/extension --only builtin The legacy name `sw-cli` is accepted in both `--only` and `--exclude` for extension and project validation, with a deprecation warning. Use `builtin` in new configurations. Reports, tool statuses, and selection errors use the canonical name `builtin`. +The `admin-twig` tool has been removed. Remove it from `--only` and `--exclude`; both now reject it as an unknown tool. It also didn't do anything before. + ### Recommended setup: Docker Run Shopware CLI through the `ghcr.io/shopware/shopware-cli` Docker image for a consistent validation environment without managing the required runtimes on the host. The primary examples on this page use Docker. @@ -144,7 +146,7 @@ Use `--format` to specify the output format (the older `--reporter` flag is depr If `--format` is not set, the format is detected automatically: `github` in GitHub Actions, `gitlab` in GitLab CI, and `summary` otherwise. -`extension validate` also reports which checkers were `invoked` or `skipped`. `Invoked` means the checker was called, not that it analyzed files or produced findings; a checker can have no applicable files. Summary and GitHub logs show a checker table before the closing summary. Markdown includes the table, JSON includes a `tools` array, and JUnit includes checker test cases. GitLab and JUnit write the human-readable table to stderr so stdout remains machine-readable. If a checker returns an execution error, the report is still emitted and the command fails. +`extension validate` and `project validate` also report which checkers were `invoked` or `skipped`. `invoked` means the checker was called, not that it analyzed files or produced findings; a checker can have no applicable files. Summary and GitHub logs show a checker table before the closing summary. Markdown includes the table, JSON includes a `tools` array, and JUnit includes checker test cases. GitLab and JUnit write the human-readable table to stderr so stdout remains machine-readable. If a checker returns an execution error, the report is still emitted and the command fails. ## Running specific validation tools @@ -152,11 +154,10 @@ By default, `extension validate` calls every registered checker. Use `--only` or | Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | | ----------------- | --------------------- | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `builtin` | ✅ (extensions only) | — | — | Extension metadata, snippets, structure, packaging. `sw-cli` is accepted as a legacy alias. Returns immediately for a project, so **projects get no metadata validation** | +| `builtin` | ✅ | — | — | Extension metadata, snippets, structure, packaging. Runs for each eligible project extension. `sw-cli` is accepted as a deprecated alias. | | `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | | `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | | `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | -| `admin-twig` | ✅ | ✅ | ✅ | Administration Twig component checks and migrations | | `storefront-twig` | ✅ | — | — | Storefront Twig checks (accessibility, inline styles); reports only | | `rector` | — | ✅ | — | PHP breaking-change and upgrade rules. **Rewrites without reporting** — nothing appears in `validate` | | `symfony-xml` | — | ✅ | — | Converts deprecated `services.xml` / `routes.xml` to YAML | @@ -203,7 +204,7 @@ When combined, `--only` selects the checkers first and `--exclude` removes check shopware-cli extension validate /path/to/your/extension --only "builtin,phpstan,eslint" --exclude eslint ``` -This runs only `builtin` and `phpstan`. Excluding every selected checker is an error for `extension validate`. +This runs only `builtin` and `phpstan`. Excluding every selected checker is an error for both `extension validate` and `project validate`. ### Running without copying the sources @@ -323,11 +324,9 @@ 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 `.config/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/` and extensions listed in `validation.ignore_extensions` 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 `builtin` 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. -::: +The `builtin` checker validates each eligible extension separately, including its metadata, icon, snippets, and structure. Each extension's `validation.ignore` rules apply only to that extension; project-level `validation.ignore` rules are then applied to the combined findings. Findings use paths relative to the project root. As with extension directory validation, `zip.disallowed_file` findings are suppressed. Use `extension validate` on a built zip file to check the release artifact. If you omit the path, `project validate` discovers the nearest Shopware project by walking up from the current directory. A directory is recognized when its Composer metadata references `shopware/core` and `bin/console` exists; `PROJECT_ROOT` overrides this discovery. @@ -337,13 +336,25 @@ If you omit the path, `project validate` discovers the nearest Shopware project | ------------------- | --------------------------------------------------------------------------------- | | `--local-only` | Only discover extensions from `custom/*` folders | | `--only ` | Run only selected tools (comma-separated) | -| `--exclude ` | Remove the listed checkers from the selection after applying `--only` | +| `--exclude ` | Exclude checkers from all checkers or the `--only` selection | | `--no-copy` | Analyze the project in place instead of copying it to a temporary directory first | | `--format` | Reporting format (`summary`, `json`, `github`, `gitlab`, `junit`, `markdown`) | -`project validate` also runs its registered checkers by default. It has no `--full` flag. `builtin` is included in that registry but returns immediately without a single-extension context; `--only builtin` therefore reports no metadata findings. The legacy `--only sw-cli` alias is also accepted. Use `extension validate` to check an individual extension. `project validate` also has no `--check-against`; that flag exists only on `extension validate`. +`project validate` runs every registered checker by default, including `builtin` for each eligible extension. Use `--only builtin` to run only the built-in extension checks. The legacy `--only sw-cli` alias is accepted with a deprecation warning. Project validation has no `--full` or `--check-against` flag; `--check-against` exists only on `extension validate`. + +Project validation uses the same checker names as extension validation. Without `--only`, exclusions apply to all checkers; when both flags are supplied, exclusions apply to the selected set. Unknown names, exclusions outside that set, empty final selections, and invalid report formats fail before tool setup or copying. Reports include checker invocation statuses as described in [Output formats](#output-formats). Unlike extension validation, project validation initializes external tooling even when only native checkers are selected. + +```shell +shopware-cli project validate --only builtin +shopware-cli project validate --exclude "eslint,stylelint" +shopware-cli project validate --only "builtin,phpstan,eslint" --exclude eslint +``` + +Use `--verbose` with `project validate`, `project fix`, or `project format` to log source directories, extension names, and external tool commands and arguments. For example: -Project validation uses the same checker names and applies `--exclude` after `--only`, rejecting names outside the selected set. It does not include checker invocation statuses in its reports. Unlike extension validation, it initializes external tooling even when only native checkers are selected. +```shell +shopware-cli project validate --only phpstan --verbose +``` Use `--local-only` when you want extension discovery limited to the `custom/*` folders: From 5a8cdf8cb12c77c35bfae28a9aa2470dc2c289b0 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Tue, 6 Oct 2026 17:04:40 +0200 Subject: [PATCH 6/6] fix: markdown formatting --- products/tools/cli/formatter.md | 16 ++++++++-------- products/tools/cli/validation.md | 22 +++++++++++----------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/products/tools/cli/formatter.md b/products/tools/cli/formatter.md index 18ac147bbc..9211c180d5 100644 --- a/products/tools/cli/formatter.md +++ b/products/tools/cli/formatter.md @@ -89,11 +89,11 @@ Both flags accept comma-separated names. An unknown name, an excluded formatter The following table summarizes the extension format options: -| Flag | Description | -| ------------------- | -------------------------------------------------------------- | -| `--only ` | Run only the specified comma-separated formatters | +| Flag | Description | +| ------------------- | ---------------------------------------------------------------- | +| `--only ` | Run only the specified comma-separated formatters | | `--exclude ` | Exclude formatters from all formatters or the `--only` selection | -| `--dry-run` | Check formatting without modifying files | +| `--dry-run` | Check formatting without modifying files | ## Format a project @@ -141,10 +141,10 @@ If you omit the path, `project format` discovers the nearest Shopware project by ### Project format options -| Flag | Description | -| ------------------- | --------------------------------------------------------------- | -| `--dry-run` | Check formatting without modifying files | -| `--only ` | Run only the specified comma-separated formatters | +| Flag | Description | +| ------------------- | ---------------------------------------------------------------- | +| `--dry-run` | Check formatting without modifying files | +| `--only ` | Run only the specified comma-separated formatters | | `--exclude ` | Exclude formatters from all formatters or the `--only` selection | The path argument is optional for `project format` but required for `extension format`. diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 1d4cf0c7d9..ced018bb49 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -152,17 +152,17 @@ If `--format` is not set, the format is detected automatically: `github` in GitH By default, `extension validate` calls every registered checker. Use `--only` or `--exclude` to narrow the selection. The available tool capabilities are: -| Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | -| ----------------- | --------------------- | ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `builtin` | ✅ | — | — | Extension metadata, snippets, structure, packaging. Runs for each eligible project extension. `sw-cli` is accepted as a deprecated alias. | -| `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | -| `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | -| `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | -| `storefront-twig` | ✅ | — | — | Storefront Twig checks (accessibility, inline styles); reports only | -| `rector` | — | ✅ | — | PHP breaking-change and upgrade rules. **Rewrites without reporting** — nothing appears in `validate` | -| `symfony-xml` | — | ✅ | — | Converts deprecated `services.xml` / `routes.xml` to YAML | -| `php-cs-fixer` | — | — | ✅ | PHP code style (Shopware Coding Standard) | -| `prettier` | — | — | ✅ | JavaScript, Vue, TypeScript, CSS, SCSS formatting | +| Tool | Reports in `validate` | Rewrites in `fix` | Formats in `format` | Notes | +| ----------------- | --------------------- | ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `builtin` | ✅ | — | — | Extension metadata, snippets, structure, packaging. Runs for each eligible project extension. `sw-cli` is accepted as a deprecated alias. | +| `phpstan` | ✅ | — | — | PHP static analysis; returns without analyzing apps (no `composer.json`) | +| `eslint` | ✅ | ✅ | — | JavaScript, Vue, TypeScript with Shopware-specific rules | +| `stylelint` | ✅ | ✅ | — | CSS/SCSS with Shopware standards | +| `storefront-twig` | ✅ | — | — | Storefront Twig checks (accessibility, inline styles); reports only | +| `rector` | — | ✅ | — | PHP breaking-change and upgrade rules. **Rewrites without reporting** — nothing appears in `validate` | +| `symfony-xml` | — | ✅ | — | Converts deprecated `services.xml` / `routes.xml` to YAML | +| `php-cs-fixer` | — | — | ✅ | PHP code style (Shopware Coding Standard) | +| `prettier` | — | — | ✅ | JavaScript, Vue, TypeScript, CSS, SCSS formatting | Each command selects only tools that support its operation. An unsupported `--only` name is an error that lists the available tools for that command; for example, `validate --only prettier` and `fix --only phpstan` are errors.