diff --git a/products/tools/cli/automatic-refactoring.md b/products/tools/cli/automatic-refactoring.md index 1809bf4af2..e502767bce 100644 --- a/products/tools/cli/automatic-refactoring.md +++ b/products/tools/cli/automatic-refactoring.md @@ -34,27 +34,28 @@ 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()`: +By default, a `fix` command invokes every registered fixer. The following tools support fixing: | Tool | What it fixes | Version-aware | Implementation | | ------------- | -------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | | `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 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). +- `phpstan`, `storefront-twig`, and `builtin` 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` 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 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 @@ -93,15 +94,25 @@ 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: + +```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 ` | 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. @@ -135,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**. @@ -177,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 eabd21d314..9211c180d5 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. @@ -20,15 +20,16 @@ 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()`: +By default, a `format` command invokes every registered formatter. The following tools support formatting: | Tool | What it formats | Implementation | | -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `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) | -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` 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 @@ -70,6 +71,30 @@ 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,prettier" +``` + +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. + +The following table summarizes the extension format options: + +| 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 | + ## Format a project @@ -116,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`. @@ -129,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/index.md b/products/tools/cli/index.md index 22e9c97c54..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 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`, `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. +`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/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 14ad1cd8b4..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 tool names. +`--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 78899e1343..ced018bb49 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -11,20 +11,28 @@ 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 Storefront Twig linter provide additional checks. -:::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`. -::: +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`. + +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. -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. 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 @@ -46,16 +54,16 @@ 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. -## 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: @@ -74,7 +82,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. @@ -85,36 +93,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, 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. +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. @@ -138,33 +146,25 @@ 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. -## Running specific validation tools +`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. -With `--full`, `extension validate` calls the validation check implemented by each registered tool. The tools that currently add validation findings 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`) | -| `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 | +## Running specific validation tools -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. +By default, `extension validate` calls every registered checker. Use `--only` or `--exclude` to narrow the selection. The available tool capabilities are: -### Which tools each command actually runs +| 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 | -| 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,44 +179,52 @@ 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. Without `--only`, that set contains every checker: + +```shell +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. + +When combined, `--only` selects the checkers first and `--exclude` removes checkers from that selection: ```shell -docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension validate --full /ext --exclude "eslint,stylelint" +shopware-cli extension validate /path/to/your/extension --only "builtin,phpstan,eslint" --exclude eslint ``` -Both flags accept a comma-separated list and fail with an error if a tool name does not exist. +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 -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. 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 --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. @@ -230,14 +238,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. @@ -254,7 +262,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/') @@ -266,7 +274,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. @@ -316,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 `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. -::: +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. @@ -330,11 +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 ` | Run all tools except the listed ones | +| `--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` 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` 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: + +```shell +shopware-cli project validate --only phpstan --verbose +``` Use `--local-only` when you want extension discovery limited to the `custom/*` folders: