- How do I install PHPCompatibility in a Laravel project?
- Install it as a dev-only dependency with composer require --dev phpcompatibility/php-compatibility, plus squizlabs/php_codesniffer. Register the standard either by letting dealerdirect/phpcodesniffer-composer-installer handle installed_paths automatically, or by running phpcs --config-set installed_paths vendor/phpcompatibility/php-compatibility. Then add a phpcs.xml.dist that references the PHPCompatibility standard and a testVersion range, and run vendor/bin/phpcs from your CI step. A single engineer can have a working proof of concept against one module in under a day.
- Is wimg/php-compatibility abandoned? Which Composer package should I use?
- Yes, wimg/php-compatibility is the legacy, abandoned package name. The actively maintained package on Packagist is phpcompatibility/php-compatibility, which maps to the PHPCompatibility/PHPCompatibility repository. Any composer.json or lock file still referencing the old name is a red flag you should resolve before rolling this out. Swapping the name is usually a drop-in change because the ruleset and sniff names are identical.
- How do I set which PHP versions PHPCompatibility should check against?
- Use the testVersion config value in your phpcs.xml.dist, for example <config name="testVersion" value="8.1-8.4"/>, which checks that code runs on every version in that range. A single value such as 8.3 checks only that version, and you can combine with a leading or trailing dash to express open-ended ranges. If testVersion is not set, the sniffs fall back to the PHP version of the executable running PHPCS, which is rarely the target you actually want. Always set it explicitly and commit it alongside the ruleset.
- Which PHP_CodeSniffer version is compatible with PHPCompatibility?
- PHPCompatibility 10.x is the line that targets PHP_CodeSniffer 4.x, while codebases pinned to PHPCS 3.x must stay on PHPCompatibility 9.x. Version skew between the two is the single most likely cause of a silently broken compatibility gate, so pin both explicitly in composer.json. Also make sure your PHPCS version can tokenize the newest PHP syntax in your codebase, otherwise newer syntax may parse incorrectly.
- Why does PHPCompatibility report zero errors in my CI pipeline?
- The most common causes are a misconfigured installed_paths, so the standard never loads, or a missing or wrong testVersion. Run phpcs -i to confirm PHPCompatibility is listed among the installed standards before trusting a green build. Because the tool is detection-only, a passing run with no findings looks identical to a run where nothing was checked, so guard against this with a known-violation smoke test fixture that must fail the build.
- How is PHPCompatibility different from PHPStan, Larastan or Psalm?
- PHPCompatibility only answers one question: will this code run on the PHP version I am targeting? It flags removed functions, changed signatures, deprecated ini directives and syntax that requires a newer or older PHP. PHPStan, Larastan and Psalm do type and semantic analysis instead. They are complementary, and most teams run PHPCompatibility in the same fast, dependency-free CI tier as linting and static analysis.
- Can PHPCompatibility automatically fix incompatible code?
- No, it is detection-only and produces findings rather than fixes, which is why PHPCS may show the sniff as non-fixable. The usual pattern is to pair it with Rector so detection closes the loop into automated remediation. Even then, review Rector diffs manually, because a polyfill or a version-guarded code path sometimes makes the reported issue a false positive.
- Does PHPCompatibility work with Laravel and framework-specific APIs?
- Yes, it is framework agnostic and works on any Composer-based PHP project, including Laravel monorepos and legacy applications. It only understands the PHP language and its extensions, so it will not flag Laravel or Symfony API deprecations. Use it alongside Laravel-focused tooling such as Larastan and Rector for framework-level upgrade coverage.
- How do I stop false positives from polyfills or exclude specific sniffs?
- Polyfills such as symfony/polyfill make newer functions safe on older PHP, so the sniffs will flag code that is actually fine. Exclude the relevant sniffs in phpcs.xml.dist, or use the Paragonie compat standards and the WordPress-specific PHPCompatibilityWP standard where applicable. Prefer documented ruleset exclusions over scattered inline ignores, and record the justification next to each exclusion so the suppression does not quietly grow over time.
- Is the LGPL-3.0 license a problem for a Laravel application?
- PHPCompatibility is licensed LGPL-3.0, which is a copyleft license, but as a dev-time tool that is not redistributed with your product the obligations are generally not triggered. The risk rises if you vendor the sniffs into a distributed artifact or an internal platform image that ships to customers. Have legal confirm your specific setup before standardizing on it, especially for shipped Docker images or SDKs.