SymPress QA

Shared QA tooling for SymPress packages.

This package does not replace sympress/coding-standards. The coding standards package remains responsible for PHPCS rulesets and custom sniffs. sympress/qa provides the shared toolchain, PHPStan defaults, PHPUnit templates, and the qa runner used by package scripts and CI.

The runner is a Symfony Console application and uses Symfony Process for tool execution. It is designed to behave the same in a standalone split package, in the SymPress monorepo, and inside CI containers.

When a monorepo root targets a package via --package, the runner prefers the root or QA toolchain before a package-local vendor/bin. That keeps direct monorepo checks deterministic even when an individual package still has an older local vendor directory. PHPCS and PHPCBF are executed with PHP deprecation notices suppressed, so dependency deprecations in coding-standard tooling do not abort scans on newer PHP runtimes.

Installation

composer require --dev sympress/qa

The package intentionally keeps PHPCS, PHPStan, PHPUnit and their extensions in require. Downstream packages install sympress/qa as a dev dependency and receive the complete QA toolchain transitively.

Composer Scripts

Recommended package scripts:

{
  "scripts": {
    "cs": "qa cs",
    "cs:fix": "qa cs:fix",
    "static-analysis": "qa static-analysis",
    "tests": "qa tests",
    "test": "@tests",
    "qa": [
      "@cs",
      "@static-analysis",
      "@tests"
    ]
  }
}

Packages can still keep custom implementations behind the same script names. CI should call composer qa and let each package decide whether it uses sympress/qa or custom commands.

Commands

vendor/bin/qa cs
vendor/bin/qa cs:fix
vendor/bin/qa static-analysis
vendor/bin/qa tests
vendor/bin/qa qa
vendor/bin/qa qa --strict
vendor/bin/qa doctor --strict

Unavailable gates are visibly reported as SKIP by default. Add --strict to a tool command or to qa when an unavailable gate must fail. Use doctor --strict with an adoption file to verify that required gates are configured and referenced by composer qa.

DevOps Usage

CI jobs can keep their package-specific behavior simple:

composer install --prefer-dist --no-progress --no-interaction
composer qa

Packages that need custom behavior can keep the same Composer script names and wrap custom commands behind them. The runner also supports direct package targeting from a monorepo root:

php packages/qa/bin/qa qa --package=packages/kernel
php packages/qa/bin/qa doctor --strict --package=packages/kernel

doctor --strict checks only configured required gates. Missing optional gates are reported as planned work when an adoption file is present; without one, cs is the only required default.

The adoption format is defined by docs/qa-adoption.schema.json. Invalid JSON, schema-incompatible data or an unsupported version always fails instead of silently loading defaults. This repository's own composer qa runs all gates in strict mode.

Config Includes

PHPStan configs can include shared defaults:

includes:
    - vendor/sympress/qa/config/phpstan/library.neon

parameters:
    paths:
        - src
        - tests

WordPress packages can use:

includes:
    - vendor/sympress/qa/config/phpstan/wordpress.neon

parameters:
    paths:
        - src
    bootstrapFiles:
        - tests/Support/TestEnvironment.php

szepeviktor/phpstan-wordpress is installed by this package and should be loaded through phpstan/extension-installer. Consuming packages need to allow the Composer plugin:

{
  "config": {
    "allow-plugins": {
      "phpstan/extension-installer": true
    }
  }
}

PHPCS remains package-local through phpcs.xml.dist, usually referencing SymPress-Pure, SymPress-WordPress, SymPress-Boundary, or SymPress-Templates.