Using PhpStorm Inspections as a First Line of Defense in Legacy PHP Codebases

Legacy PHP codebases rarely get a clean static analysis pass on day one. The real problem is not the lack of tools, it is the noise-to-signal ratio. Turn on every check and the editor lights up with thousands of warnings. Turn them off and real bugs slip through. PhpStorm’s built-in inspection engine, paired with incremental integration of external analyzers like PHPStan or Psalm, gives a practical way to get immediate local feedback without forcing a big-bang refactor.

The local feedback loop you already have

PhpStorm ships with a PHP inspection engine that runs while you type. Inspections are static checks for type mismatches, undefined variables, unused code and probable bugs. Unlike a CLI tool, they require no external command and surface in the editor gutter as you edit.

This matters for legacy work because the feedback is local and fast. You can see a probable bug the moment you open a file, without waiting for a CI run. The engine is separate from external analyzers, so its rule set is stable and versioned with the IDE. Menu locations for inspections are version-sensitive, so verify the exact path in your release under Settings/Preferences > Editor > Inspections.

Scope inspections instead of toggling them globally

For legacy code, the engineering decision is scoping. Inspections can be enabled per category and scoped by folder or file type, suppressed with inline annotations, and exported to shared IDE settings. That lets a team standardize quality rules without modifying code.

A common pattern is a baseline profile. Keep core PHP errors on everywhere, such as Undefined variable and Type compatibility, and keep stylistic or strict type hints off in old directories. Use per-folder scopes to isolate legacy modules while new code lives under stricter rules. Suppressions can be applied with inline comments or annotations for known legacy exceptions, which documents the intent without hiding the rule globally.

Sharing is done by exporting the inspection profile from Settings/Preferences > Editor > Inspections and committing it as a team settings file. Local IDE configuration alone does not enforce quality in CI, so mirroring the key rules in pipeline is needed for team consistency.

Layer PHPStan or Psalm incrementally

PhpStorm supports integration with external static analyzers through native support and plugins. The value is incremental adoption. Built-in inspections give immediate feedback; PHPStan or Psalm provide deeper data-flow analysis and configurable levels.

Because the two systems use different rule sets, findings will diverge. Expect that. Align expectations by using PhpStorm inspections for fast local signals and the external analyzer for stricter, level-based checks that can be gated in CI.

A practical worked example is a baseline inspection profile plus a rising PHPStan level. First, create a profile that enables core PHP errors like Undefined variable and Missing return type, and disable noisy inspections in legacy folders. Export and share the profile.

Next, enable PHPStan integration in PhpStorm and point it at a phpstan.neon configuration. Start at a low level for the whole codebase and raise the level only for new modules or files. Warnings from the external analyzer appear alongside inspections, letting developers see both signals in one view. Legacy warnings can be isolated with baseline files provided by the analyzer, keeping the day-to-day signal clean.

Trade-offs and limitations

Aggressive inspections increase noise in legacy code and can increase indexing load on very large projects. Built-in inspections and external analyzers do not produce identical results, so developers need to learn which signal to trust for which case.

Inspection names and settings locations are version-sensitive across PhpStorm releases. Verify in your version that categories such as Undefined variable and Type compatibility are present and toggleable.

A practical way to check the result is to create a small test PHP file with an undefined variable and a missing return type and confirm inspection highlights appear in the editor. Then open the Plugins section and verify that analyzer level and configuration file settings are recognized by the IDE.

Do not rely on IDE settings for enforcement. Share the profile and mirror the essential rules in CI so quality is consistent across machines.