Download the PHP package rampart/quality-checker without Composer

Overview

quality:check is a single Artisan command that runs the whole quality pipeline and produces one of: a console table, JSON, HTML or Markdown report. It returns a predictable exit code you can wire directly into your CI pipeline.

The package philosophy:

• Wrap, don't rewrite — standard tools are invoked via their CLI and their output is parsed.
• Custom analyzers only where needed — security heuristics, missing-test detection and convention rules are implemented with PHP-Parser over the AST.
• Zero-config by default — it runs right after install, and is configurable to disable or extend rules.
• CI-friendly — non-zero exit on failure, JSON machine-readable output.

Features

• One command to rule them all: php artisan quality:check
• Multiple report formats: console, json, html, md, sarif (or all)
• Enterprise HTML report: collapsible file groups, clickable file links (vscode:// or GitHub blob), inline code snippets, severity/top-rule charts, sortable tables, dark mode, print stylesheet, OWASP drill-down
• Standardised exit codes for CI gates
• Dependency security audit (composer audit)
• Optional filesystem security scan (trivy)
• Custom AST analyzers for security, missing tests and conventions
• Baseline support to "accept" existing issues and only report new ones
• Auto-fix of fixable issues via phpcbf (--fix)
• Cache for analyzer results (--no-cache to bypass)
• CI mode (--ci) and JSON shortcut (--json)

Requirements

Optional tools (skipped with a hint if missing): squizlabs/php_codesniffer, phpstan/phpstan, phpunit/phpunit, trivy.

Installation

Requirements: PHP ^8.1, Laravel 9|10|11|12, and Composer 2.4+.

The service provider is auto-discovered. Publishing the config is optional, but recommended when you want to change paths, tiers, tool settings, or enable Trivy:

This creates config/quality-checker.php.

Using a local clone during development

When developing the checker itself, clone it next to the Laravel application:

From the Laravel application's directory, register the local checkout and install the package from that path:

The relative path must point from the Laravel application's directory to the cloned checker directory. Composer creates a symlink/junction where supported, so source changes in the clone are immediately used by the application. After pulling package changes, run:

For a normal application installation, omit the path repository and use the stable package version instead:

Two Ways to Run

The same engine, the same analyzers, the same reports and the same exit codes. Two entry points, because the situations they serve are genuinely different.

Use the Artisan command for your own application: it has the target's dependencies, its config file, its phpunit suite, and the full option set including --fix, --ignore, --ci and --json.

Use the standalone binary when the target cannot take the dependency — version conflicts, a legacy toolchain, a read-only mount, a codebase you are auditing but not building. It needs nothing from the target beyond PHP.

Both write the same five report formats and both return 0 / 1 / 2 for pass / gate-failed / environment-error, so a CI job can switch between them without changing how it interprets the result.

Options that exist on only one entry point are marked in the Options Reference.

Quick Start (5 minutes)

Run the security scan first. It is the safest first run because it does not require every optional tool to be installed:

Then run the complete local gate:

To generate all report formats in a predictable directory:

The command returns exit code 0 when the selected threshold passes and a non-zero code when the gate fails. Use --fail-on=none when reviewing findings without failing the shell command.

Viewing the HTML report

Open reports/quality-checker/quality-report.html directly in a browser — the report is fully self-contained (no network needed) and works from file://. File links use vscode:// deep links (require VS Code); set html.repo_url in the published config to get GitHub blob links instead.

Standalone scan (no install in the target project)

When the target cannot install the package (version conflicts, legacy toolchain), scan it without touching it — no vendor, no artisan needed in the target:

Defaults to --only=custom (static analyzers only). Reports land in <target>/reports/quality-checker unless --output= overrides it.

Recommended rollout for an existing project

Do not block the team on every legacy finding on the first day:

Commit baseline.json so all developers and CI use the same starting point. Only run --baseline-update after reviewing the new findings; it accepts all current findings again.

Tool installation behavior

Auto-install is off by default. If phpcs, phpstan, or phpunit is missing, the checker reports it as skipped and prints the command to install it manually. This is deliberate: installing means running composer require --dev inside your project, which edits composer.json and vendor/ before you have seen a single finding, with no undo.

To opt in:

or per run, by dropping --no-auto-install. Trivy is downloaded to the user cache and does not modify the project either way.

Options Reference

"Artisan" means php artisan quality:check, "Standalone" means php bin/quality-check <target-dir>.

Note: --json implies the JSON reporter, while --ci adds the JSON reporter automatically. --format=all maps to console,json,html,md,sarif. sarif emits quality-report.sarif (SARIF 2.1.0) for GitHub code scanning upload.

Path exclusion (analyzers.exclude_paths)

--exclude filters checker names; analyzers.exclude_paths filters files, and is the only way to keep the custom analyzers out of a directory. The shipped default is ['*/fixtures/*']: code under a fixtures/ directory exists to be vulnerable, so reporting it is noise rather than signal — a project whose test suite keeps vulnerable samples there would otherwise have to baseline them or disable the rules.

Two forms are accepted, both case-insensitive and separator-insensitive:

Excluded files are counted in the custom checker summary (N file(s) excluded by analyzers.exclude_paths), so a scan never hides scope silently. Use [] to scan everything.

Exit Codes

Checkers

When an optional tool is not installed, the corresponding checker reports skipped with a hint on how to install it.

Custom Analyzer Rules

43 rule ids across 5 groups. Every row below is verified against src/Result/RuleIds.php by RuleDocsTest, so this table cannot drift from what the analyzers actually emit — an id that does not exist, or a rule that ships undocumented, fails the build.

Severity is what the rule emits; where a rule emits more than one, both are listed. Confidence is the noise rating: high is safe to gate CI on, low is a heuristic hint. See Confidence & Tiering.

Security (analyzers/security)

Opt-in data-flow engine (analyzers.security.taint_engine, off by default):

OWASP (analyzers/owasp)

All 11 are on by default. Categories follow OWASP Top 10 (2021) — the edition the mapping encodes. The 2025 revision reorders categories; rule ids and category ids here are stable, so a category moves without renaming a rule.

Laravel (analyzers/laravel)

Test coverage (analyzers/test_coverage)

test_coverage.unified is on by default and emits the first five rules as low-confidence hints. The last two are opt-in.

Convention (analyzers/convention, off by default)

Frontend (analyzers/frontend, on by default)

Wrapped checkers

These are not rule ids — they are the third-party tools this package drives, and their findings appear in reports under the phpcs, phpstan, phpunit, composer_audit and trivy sources:

Confidence & Tiering

Every issue carries a confidence: high | medium | low.

• high → safe to gate CI (OWASP, taint, hardcoded secret, composer audit).
• medium → fairly reliable warning (env() outside config, dd() in app, insecure hash).
• low → heuristic hints, hidden unless you opt in (dead code, missing test, naming, todo).

Convention heuristics (convention.*) are off by default to avoid noise. The unified test-coverage detector is enabled by default but emits low-confidence warnings; raise --min-confidence=high or use the security tier when you want to focus on security findings only.

Severity

Every issue carries a severity, and fail_on decides which ones fail the build.

OWASP_BLADE_DYNAMIC_INCLUDE ships remapped to info. It reports every dynamic view name — @include($view), @extends('a.' . $x) — at error, because Blade has no data-flow analysis and so cannot tell a user-steerable template name from one built at runtime. Across a 27-project benchmark the Blade findings were dominated by this rule, and at error a default run came out red before the user had seen anything. At info it stays in the report without failing a build. To treat every dynamic view name as blocking:

OWASP_BLADE_XSS is not demoted, and reflected XSS still fails the gate. Its error severity fires only for request-derived output — {!! request('q') !!} and the superglobals — which is reflected XSS and worth blocking. Its ordinary {!! $model->field !!} hits are already warning and never turned a build red, so demoting the whole rule would have cost that coverage without fixing the noise.

Other rules can be remapped the same way. An unparseable severity is ignored rather than guessed, so a typo cannot silently promote a rule to error.

The tier controls what the gate fails on:

quality and all are currently identical; the distinct all behaviour is planned, not shipped. Checkers that carry no quality-gate signal (dependency audit, trivy, the heuristic analyzers) report the same in every tier — exclude them with exclude in config or --only to keep them out of a gate run.

--min-confidence filters what is reported; --tier filters what the exit code fails on.

Real-world benchmark

Custom analyzers only (phpcs/phpstan/phpunit excluded), tier=security, fail-on=none, cold runs without cache. Quality is pinned by a labeled corpus (tests/Unit/AnalyzerMetricsTest.php): precision 1.000 / recall 1.000 across 500 true/false-positive cases (340 TP + 160 TN) plus a 98-case holdout (19% blind, never used for tuning) and a 30-injection recall suite (tests/Unit/CveRecallTest.php 30/30), so the reductions below cannot regress silently.

The table is a snapshot, not a live measurement — it records one day of output by hand and no CI job re-measures it. To measure this tool on your projects, use tools/benchmark-projects.php with a local manifest of paths (see the header of that file for the format). It prints per-rule counts, prints each rule's share of all findings, and --diff=baseline.json shows what moved after an upgrade. Your manifest stays local; no project list ships with the package.

External precision on your code (7/8)

Corpus precision is internal. For your codebase:

(severity split: critical / error / warning)

Biggest single win: OWASP_BROKEN_ACCESS_CONTROL on the e-commerce target (A) 453 → 150 — actions protected by route middleware, Route::controller() groups and cross-file require are now resolved; FQCN keys keep same-named Admin/Shop controllers apart (see docs/false-positives.md).

Repeat runs are near-instant via the result cache (1 h TTL, keyed by file-set hash + tool config + analyzer code version, so package upgrades never serve stale results).

Auto-provisioning missing tools

Opt in to self-provisioning missing tools with auto_install_tools => true or by dropping --no-auto-install:

• phpcs / phpstan / phpunit — installed via composer require --dev inside the target project when missing. This edits your composer.json and vendor/. It is off by default for that reason. (Slow on very large projects.)
• trivy — downloaded as a cached binary (GitHub releases) into a per-user cache directory, never touching the target project. Default version 0.74.0 (override with trivy.version). Binary is cached, so repeat runs are offline.
• If auto-install is off or fails, a checker uses a tool already available in the target project's vendor/bin; otherwise it is reported as skipped with an install hint.

Troubleshooting

PHPUnit exits with code 255 or runs out of memory

The checker runs the target project's vendor/bin/phpunit. Large Laravel test suites may need more than PHP's default CLI memory limit. Increase the CLI memory_limit in the PHP installation used by the project, then run the check again. Confirm the test suite independently first:

The first report contains too many legacy findings

Use the baseline workflow above instead of lowering security confidence. A baseline hides only the exact existing findings; new findings still appear.

A tool is missing or the project is read-only

Run the custom analyzers and dependency audit without touching the project's dependencies — the default, so the flag is only needed if you have opted in globally:

A finding may be a heuristic false positive

Custom analyzers are static heuristics and do not replace a manual security review. Check the file and line in the report, then use a reviewed baseline or adjust the analyzer configuration rather than suppressing all security rules. See docs/false-positives.md for a per-rule guide.

Baseline Workflow

Baseline lets you "accept" the issues currently present in a project, so that only new issues are reported from then on. This is useful when introducing quality-checker to a project that already has many issues you do not want to fix immediately.

1. Generate a baseline from the current results

This writes a baseline.json file at the project root.

2. Update the baseline

This overwrites the baseline with all current issues (every severity). Only use it when you are sure the current state is the desired one.

3. Use a custom baseline file

How it works

The baseline file is a simple JSON array of signatures (each signature is md5(rule|file|line|message)):

When a baseline is loaded, issues matching a signature are excluded from the report.

Baseline in CI

For a shared team baseline, commit baseline.json to the repository so the whole team agrees on the quality threshold. If each developer should maintain their own, add baseline.json to .gitignore instead.

See docs/baseline.md for more details.

Auto-fix

--fix runs phpcbf to auto-fix fixable coding-standard issues on the scanned paths. If phpcbf is not installed, it prints a warning. Only coding-standard issues are fixable; the custom analyzers are informational only.

CI Integration (GitHub Actions)

The recommended CI workflow uses --ci (JSON output + fail-on=error) and uploads the report as an artifact.

The job fails when the exit code is non-zero, which happens when any issue reaches the error threshold (the default for --ci).

Upload findings to GitHub code scanning (SARIF)

--format=sarif emits a SARIF 2.1.0 file that GitHub Advanced Security can ingest, so security findings surface directly on the PR as code-scanning alerts:

Severity mapping: critical/error → error, warning → warning, info → note. Each rule is registered once with its highest observed severity, and OWASP/taint/security rules are tagged accordingly.

GitLab CI

A phpcs/phpstan/phpunit run needs the dev dependencies; if you install with --no-dev, add --only=custom to the gated command so the analyzer phase still runs.

Jenkins (Declarative Pipeline)

The HTML report is the artifact to link from the build page; it is self-contained and needs no server.

Azure Pipelines

Pre-commit Hook

Pre-commit hook stubs are provided at resources/stubs/pre-commit and resources/stubs/pre-commit.ps1 (Unix and PowerShell respectively). Install the relevant one into your project's .git/hooks/ (or a hooks-manager like pre-commit) to run the quality gate before every commit.

Developing & Testing the Package

Clone the repository and install dependencies:

Run the test suite:

To regenerate the optimized autoloader after adding classes:

Validate the composer.json:

The package gates itself

.github/workflows/dogfood.yml runs on every push and pull request:

1. composer check — phpcs, phpstan level 6 and the full PHPUnit suite.

2. Self-scan — the package's own analyzers over its own shipped code:

   tests/ is out of scope there on purpose: it holds deliberately vulnerable analyzer samples, which are true positives. Everything else must be clean — findings in src/ are either fixed or carry a written // quality-checker-ignore-next-line justification.

Documentation

The rule tables above are parsed by tests/Unit/RuleDocsTest.php, which fails if the docs and src/Result/RuleIds.php disagree — a rule cannot ship undocumented, and a documented id cannot be one the analyzers never emit.

License

MIT © 2026 Rampart