Versioning and Sharing PhpStorm Inspection Profiles Across a Team

1. Why the default profile rarely suffices for Magento teams

The bundled default profile in PhpStorm covers general PHP issues well but knows nothing of Magento-specific conventions or internal project agreements, such as using ViewModels instead of block classes or requiring a specific PHPDoc structure. Without adjustment, this results in either too many irrelevant warnings or too few relevant ones.

If every developer tweaks the profile locally to their own taste, the shared benchmark for code quality disappears entirely. One developer sees a warning about unused imports, another does not, leading to review discussions that the IDE should have settled beforehand.

This missing shared benchmark matters especially in projects with rotating external contractors, since every new developer initially brings their own set of inspections and thereby implicitly enforces their own idea of code quality, without that ever being a conscious team decision.

2. Creating a custom profile based on the default profile

Under Settings, Editor, Inspections, a new profile can be created from the default one via Copy Profile. From there, individual inspections can be enabled, disabled, or raised in severity from warning to error, for instance for missing type declarations.

For a PHP 8.4 project it is worth consistently setting inspections like strict types declaration, unused use statements, and missing return type declarations to error, while stylistic hints like line length are better left as warning to keep the signal to noise ratio reasonable.

It is equally worth enabling Magento-specific inspections, for example warnings about direct SQL queries instead of using the repository layer, or about missing interface implementations for new service contracts, since these patterns are naturally absent from generic PHP profiles.

3. Where the profile is stored: project level instead of IDE level

When saving, PhpStorm offers a choice between IDE scope, where the profile only exists locally, and project level, where it lands as an XML file directly inside the project folder. For a team profile, project level is the only correct choice.

A project level profile physically appears under .idea/inspectionProfiles/ in the project directory. Once this folder is checked into Git as usual, every developer gets the current version of the profile automatically on the next pull, without importing anything manually.

$ ls -la .idea/inspectionProfiles/
Project_Default.xml
profiles_settings.xml

$ git log --oneline -- .idea/inspectionProfiles/
a1c3f92 Enable inspection for missing PHPDoc blocks
7d0e441 Set severity of unused imports to ERROR

4. The XML structure of a profile in detail

Project_Default.xml lists every customized inspection as its own inspection_tool entry with class, enabled, and level. Only deviations from the factory state are stored, which keeps the file manageable and makes diffs readable in code review.

profiles_settings.xml determines which profile is treated as the active default for the project. Together, both files ensure PhpStorm loads the team profile automatically when the project opens, without any developer having to switch manually.

Anyone editing the file directly in a text editor instead of through the graphical interface should make sure the enabled_by_default attribute always matches the original factory state of that inspection, otherwise PhpStorm can produce conflicting values the next time it saves through the UI.

<component name="InspectionProjectProfileManager">
  <profile version="1.0">
    <option name="myName" value="Mironsoft Magento" />
    <inspection_tool class="PhpUnusedAliasInspection" enabled="true" level="ERROR" enabled_by_default="true" />
    <inspection_tool class="MissingReturnTypeInspection" enabled="true" level="ERROR" enabled_by_default="false" />
    <inspection_tool class="PhpFieldAssignmentTypeMismatchInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  </profile>
</component>

5. Exceptions for generated code and vendor directories

Without exceptions, a Magento project is quickly flooded with thousands of warnings from var/generated, vendor, or generated/code, even though this code is neither hand written nor edited there. Such warnings drown out real problems in the project's own app/code directory.

Under Settings, Editor, Inspections, Scope, a custom scope can be defined that excludes directories like var/generated and vendor, and this scope can then be assigned to the whole profile or to individual inspections, so analysis focuses on app/code.

In addition to var/generated and vendor, excluding generated/code and pub/static is worthwhile too, since automatically generated files live there as well, and inspecting them would only slow things down unnecessarily without ever being edited by hand.

<!-- .idea/scopes/AppCode.xml -->
<component name="DependencyValidationManager">
  <scope name="App code only" pattern="file:app/code//*&&!file:*/generated//*&&!file:*/var//*" />
</component>

6. Automatic activation for new team members

Since the profile lives in the .idea folder, new team members do not need to set anything up manually. A simple git clone or git pull is enough, PhpStorm recognizes the project level profile and activates it automatically as the default profile for that project.

A short note in the README stating that inspections are deliberately project-wide and should not be changed locally helps prevent anyone from accidentally overwriting a personal profile or silently disabling the team standard locally.

For teams with strict onboarding checklists, it helps to add the automatic profile activation as an explicit checkpoint, for example a screenshot of the expected profile name in the status bar, so deviations stand out immediately instead of only surfacing in the first code review.

7. Relationship with PHPStan, PHPCS, and the CI pipeline

Inspection profiles in PhpStorm replace neither PHPStan nor PHPCS, they complement them with instant feedback directly in the editor, before a commit even happens. PHPStan at level 5 finds deeper type errors that a pure IDE inspection often misses.

A sensible division of labor works well: inspections warn early and locally while writing code, PHPCS enforces the code style automatically, and PHPStan checks again rigorously in the CI pipeline, so no mistake depends solely on a developer's memory.

A concrete example illustrates the division of labor: a missing type declaration shows up immediately as an inspection warning in the editor, while a logical error in type inference spanning several method calls is more likely caught by PHPStan, which analyzes the entire control flow.

8. Maintaining the profile as its own review process

Changes to the team profile should go through the same review process as changes to application code. Anyone raising an inspection to error should justify why and show in the pull request how many existing warnings newly appear as a result.

It is advisable not to change the profile too often, since every change potentially generates hundreds of new warnings across the whole project. A calm but consistently maintained core of a few mandatory rules works better in practice than a constantly growing rule set.

A proven rhythm is a quarterly team review of the profile, where the team jointly decides whether new inspections from recent PhpStorm versions should be adopted, instead of making changes irregularly and without coordination.

9. Inspection profiles compared to PHPStan, Psalm, and PHPCS

Inspection profiles work directly in the editor and give instant visual feedback but are tied to PhpStorm and do not run in the CI pipeline. PHPStan and Psalm are static analysis tools that run independently of the IDE in any environment and are suited for hard build gates.

PHPCS focuses on formatting and coding standards, while inspections and PHPStan tend to target logical errors and type problems. For a robust setup, all three tools complement each other rather than replacing one another, with the inspection profile delivering the fastest feedback.

In practice, teams that consistently combine all three tools spend noticeably less time in late-stage code reviews on pure style or type discussions, since most of these questions are already resolved automatically before the commit happens.

10. Summary

11. FAQ: Team Inspection Profiles: The Essentials at a Glance