Weave Code
Phpstan Warroom Rules Laravel Package
script-development/phpstan-warroom-rules
Custom PHPStan rules for Laravel projects that catch script-development conventions and common pitfalls. Drop-in config, clear error messages, and fast static analysis for CI pipelines.
Canonical PHPStan rules enforcing war-room doctrine across script-development Laravel territories.
Frequently asked questions about Phpstan Warroom Rules
- How do I install script-development/phpstan-warroom-rules in a Laravel project?
- Require it as a dev dependency with composer require --dev script-development/phpstan-warroom-rules:^0.11, then include the shipped ruleset in your phpstan.neon. It is a PHPStan extension only, so it adds no service provider and no application code. Commit the composer.lock change so every territory builds against the same rule version.
- Does this package add any runtime or production dependencies?
- No. It is a dev-only Composer package with no runtime footprint, no production dependency and no migration surface in the application. Nothing is loaded during a request, so deploying the app does not change. The only effect is on static analysis runs, typically in CI or a local pre-push check.
- Which PHPStan and Laravel versions does phpstan-warroom-rules support?
- Check the composer.json constraint in the tagged release before pinning, because v0.11.0 is a 0.x line and that constraint is the authoritative source for the supported PHPStan range. The rules use reflection and the PHPStan Type API, so a PHPStan upgrade should be treated as a compatibility event for this package. Run the rules against a branch before bumping PHPStan fleet-wide.
- How do I configure narrowingHelperNamespacePrefixes for my own namespace?
- The rules narrow on a single narrowingHelperNamespacePrefixes list that defaults to ['App'] and matches on namespace boundaries. If a territory's first-party boundary code lives under a different root, add that prefix instead of forking the package. Namespace-boundary matching means AppExtra is not silently treated as App, so list each root explicitly.
- What kinds of bugs do the War Room PHPStan rules actually catch?
- They target Script Development conventions and common pitfalls around helper boundaries, credential-derived cache keys and cast bypasses. Real findings during rollout included a sentinel-seeded array that unlocked a forceDelete(), a gender persisted as an empty SET, and a missing node parsed as now() and written as a date of birth. Detection is shape-keyed on the call signature rather than a maintained list of helper names, so renamed helpers are still caught.
- How do I suppress a false positive from these rules?
- Use an inline @phpstan-ignore naming the specific rule identifier, ideally with an owner and an expiry so the ignore does not become permanent noise. The package's stated posture is that false negatives are acceptable and false positives are not, which is why that escape hatch exists. Avoid disabling whole rules in phpstan.neon, since that hides future genuine findings across the territory.
- Why did bumping from ^0.10 to ^0.11 break my previously clean PHPStan build?
- ^0.10 does not satisfy ^0.11, so no project is adopted automatically; every territory that bumps will see new errors in code that was previously clean. That is intentional and the findings are usually real bugs, but it means the pin bump is a remediation project rather than a routine version bump. Budget time for fixes and track any ignores with an owner and expiry.
- Does a green PHPStan run mean my data integrity is verified?
- No. The rules deliberately miss non-literal fallbacks, helper results laundered through a variable, and cases such as a ?? null whose null is later swallowed by Carbon::parse. A passing build means the covered shapes were not found, not that the domain logic is correct. Treat green as one signal and keep review and tests for the rest.
- How do I test that ForbidCredentialDerivedCacheKeyRule is actually working in my app?
- Add a planted positive control: a cache key derived from a credential in a test fixture, and assert that PHPStan reports it. The rule is silent on a consumer with no encrypted cast, so a clean run there is not evidence the rule works. Make the planted control part of CI so a future refactor cannot quietly neuter the check.
- How stable is this package, and does it couple to PHPStan internals?
- It is a 0.x package, so minor releases can change behaviour for consumers; pin an exact version and read the release notes before bumping. It leans on PHPStan reflection and the Type API, including TypeCombinator, per-member scalar probes and parent::casts() override order, so PHPStan upgrades are the main maintenance risk. Track which PHPStan version each territory runs so an upgrade does not land as a surprise.
Weaver
How can I help you explore Laravel packages today?