Qa Tooling Wrapper Laravel Package

Getting Started

wyrihaximus/qa-tooling-wrapper is a Composer meta-package: it ships no application code you call directly. Its job is to pull a curated QA toolchain into vendor/bin. Day-to-day, you interact with those binaries and your project’s config files, not with the wrapper’s namespace.

Minimal setup

composer require --dev wyrihaximus/qa-tooling-wrapper
ls vendor/bin
vendor/bin/phpunit --version
vendor/bin/phpstan --version

Then add the configs your project needs and wire the tools into Composer scripts or a Makefile.

Where to look first

1. The README’s generated “Included tooling” block — it is version-specific.
2. vendor/wyrihaximus/qa-tooling-wrapper/composer.json — the authoritative list of require entries for the version you installed.
3. vendor/bin — the actual developer interface.
4. wyrihaximus/makefiles — use it if you want the author’s prebuilt targets; otherwise write your own scripts.

First use case

For a Laravel app, start with the test runner and static analysis:

vendor/bin/phpunit
vendor/bin/phpstan analyse app --level=5 --memory-limit=1G

Then commit phpunit.xml, phpstan.neon, and whichever style/rector config matches the tools present in your installed version. For Laravel, add larastan/larastan separately so PHPStan understands Eloquent models, facades, and service providers.

Important framing

This is not a Laravel package. There is no service provider, no publishable config, and no runtime integration. It belongs in require-dev. Its value is convenience and version alignment; its cost is that the wrapper, not your app, chooses the tool versions.

If Composer prompts about plugins during install, resolve that before CI. Tools such as ergebnis/composer-normalize, phpstan/extension-installer, or infection/extension-installer may need explicit allow-plugins entries.

Implementation Patterns

Use it as a toolchain BOM

Rather than requiring PHPStan, PHPUnit, PHP-CS-Fixer, Rector, Infection, and normalization tools individually, require the wrapper once and let it define the set. This is the cleanest use case: one dev dependency, one upgrade path, consistent binaries across repositories.

{
    "require-dev": {
        "wyrihaximus/qa-tooling-wrapper": "^1.0"
    }
}

Pin a major version in real projects. Upgrade deliberately with:

composer update wyrihaximus/qa-tooling-wrapper --with-all-dependencies

Own your configuration files

The wrapper provides binaries, not project policy. Commit the configs you actually use:

Only reference tools that are actually present in your installed release. Check vendor/bin and the wrapper’s composer.json first.

Composer scripts pattern

Composer automatically resolves vendor/bin binaries in scripts:

{
    "scripts": {
        "qa": [
            "@test",
            "@static",
            "@style"
        ],
        "test": "phpunit",
        "static": "phpstan analyse --memory-limit=1G",
        "style": "php-cs-fixer fix --dry-run --diff"
    }
}

Use composer qa locally before pushing. In CI, run tools as separate jobs where possible so failures are attributable and parallelizable.

CI pattern

- run: composer install --no-interaction --prefer-dist
- run: composer validate --strict
- run: composer normalize --dry-run
- run: vendor/bin/phpstan analyse --memory-limit=1G
- run: vendor/bin/phpunit
- run: vendor/bin/php-cs-fixer fix --dry-run --diff

Add Rector dry-runs and Infection on a schedule or a separate non-blocking job. Cache Composer downloads plus tool caches such as .phpstan/cache and .php-cs-fixer.cache.

Extension-package pattern

If you maintain packages that extend wyrihaximus/test-utilities, depend on this wrapper instead of test-utilities to avoid circular dependency chains. That is the package’s stated architectural purpose. Application projects that want test helper classes should use test-utilities directly; projects that only want the binaries can use the wrapper.

Baseline and ratchet pattern

For existing Laravel codebases, generate a PHPStan baseline once, commit it, and ratchet the level upward. Keep the baseline small and regenerate it after wrapper upgrades rather than letting it become a permanent suppression layer.

Prefer explicit direct dependencies for extensions

If you need Larastan, Pest, a PHPStan extension, or a custom coding-standard package, require it directly in your root composer.json. Do not rely on the wrapper’s transitive dependency graph for anything your config references by name.

Gotchas and Tips

“Works out of the box” is relative. The wrapper supplies binaries; it does not supply your phpstan.neon, phpunit.xml, or fixer rules. Without project configs, tools may analyze the wrong paths or fail on defaults.

Plugin allowlists break CI. Composer 2.2+ blocks unapproved plugins. Set config.allow-plugins explicitly for the plugins actually installed, or composer install --no-interaction will fail in CI. Only enable plugins you recognize.

Transitive tools are not a stable API. A tool may be present today because the wrapper requires it, and absent after an upgrade. If your scripts or CI call vendor/bin/rector or vendor/bin/infection, confirm it exists in the installed version and consider requiring it directly if it is critical to your workflow.

Watch for version conflicts with Laravel’s own dev dependencies. Laravel ships phpunit/phpunit, laravel/pint, and sometimes other QA packages. The wrapper may constrain different versions. Diagnose with:

composer why-not phpunit/phpunit ^11
composer why phpstan/phpstan
composer show --tree wyrihaximus/qa-tooling-wrapper

If the wrapper pins an older major than your app needs, either wait for a wrapper release, require the tool directly, or skip the wrapper for that project.

Pick one style fixer. Running laravel/pint and the wrapper’s PHP-CS-Fixer rules against the same code creates churn and conflicting diffs. Choose one as the source of truth and disable or remove the other from CI.

Pest is not automatically configured. If the wrapper brings PHPUnit, Pest can still be installed and run on top of it, but Pest’s config and plugins are your responsibility. Do not assume the wrapper includes Pest.

PHPStan needs Laravel-aware setup. Vanilla PHPStan will report false positives on facades, magic properties, and container bindings. Install Larastan, include its extension, and bootstrap the application if needed. Use --memory-limit=1G for larger apps.

composer normalize rewrites composer.json. Run it on a clean working tree and review the diff. It may reorder keys and reformat sections. This is useful for consistency but noisy if mixed into unrelated changes.

Dependency-audit tools can false-positive on Laravel. composer-require-checker, composer-unused, and parallel-lint tools may flag dynamic class loading, service providers, or config-driven references. Configure excludes for bootstrap/cache, storage, generated files, and framework conventions before making them blocking.

Infection is expensive. Mutation testing against a full Laravel suite is slow and needs a coverage driver. Run it nightly, on changed files, or with a modest MSI threshold rather than on every pull request.

Baselines age badly. After upgrading the wrapper, regenerate phpstan-baseline.neon and review removed/added ignores. A stale baseline can hide new errors or fail on line-number changes.

Keep it out of production. It belongs in require-dev. Verify deployment uses composer install --no-dev; accidentally promoting it to require ships QA tooling into production images.

Low adoption means low bus factor. With zero dependents and a single maintainer, treat upgrades as deliberate dependency changes. Pin versions in CI, commit composer.lock for applications, and be prepared to replace the wrapper with an explicit require-dev list if maintenance stalls. The individual tools are standard; the wrapper is only convenience.

Debugging checklist

composer show wyrihaximus/qa-tooling-wrapper
composer show --tree wyrihaximus/qa-tooling-wrapper
composer why-not <package> <version>
composer diagnose
vendor/bin/phpstan --debug
vendor/bin/phpunit --testdox

If a binary behaves unexpectedly, check vendor/bin/<tool> --version first. The wrapper’s purpose is to decide which version you get; confirming that version is usually the fastest way to explain the behavior.