EditorConfig, Code Style and Team Consistency in PhpStorm

1. The team consistency problem and why it needs tooling

In every team with more than one person, the same pattern emerges: developer A prefers tabs, developer B prefers spaces. C's IDE formats brackets differently from D's. The result is diffs where whitespace changes bury the actual code changes, git blame becomes useless, and code reviews take longer. These problems can't be solved by coding guidelines alone, because guidelines can't be enforced consistently by hand.

The solution lies in three layers of tooling that interlock: EditorConfig ensures that baseline formatting such as indentation and line endings is treated identically in every editor. PHP CS Fixer or PHP_CodeSniffer format and check PHP files against defined rules. PhpStorm inspections surface code quality issues right while writing, before the code is even committed. Together these layers form an automated quality net.

The cost of missing consistency is concretely measurable: whitespace diffs increase review effort, inconsistent formatting slows down reading someone else's code, and differing standards between IDE configurations lead to code being reformatted again by someone's own IDE right after a formatting commit from someone else. Tooling-based consistency solves these problems once, permanently.

2. EditorConfig: the baseline layer for every editor

An .editorconfig file at the project root is the lowest common denominator for every editor, PhpStorm, VS Code, Vim, Emacs. It defines basic formatting rules such as indentation style (indent_style = space), indentation depth (indent_size = 4), line endings (end_of_line = lf), character set (charset = utf-8) and whether trailing whitespace should be trimmed (trim_trailing_whitespace = true). This file is checked into the repository and applies to every team member regardless of their IDE.

For PHP projects, Magento 2 in particular following PSR-2 and PSR-12, an .editorconfig that explicitly configures PHP files with 4 spaces but defines its own rules for YAML, JSON and other file types is recommended. Magento 2, for example, uses 4 spaces for PHP but 2 spaces for XML layout files. EditorConfig supports extension-specific sections with glob patterns such as [*.{php,phtml}] and [*.xml].

An often overlooked detail: the root = true declaration at the top of the file prevents EditorConfig from searching for parent .editorconfig files. Without this declaration, an .editorconfig in the developer's home directory could override the project rules. In monorepo setups with multiple projects in subdirectories, each subdirectory can have its own .editorconfig that overrides the parent rules for its own scope.

# .editorconfig (Magento 2 / Hyvä project)
# https://editorconfig.org
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{php,phtml}]
indent_style = space
indent_size = 4
max_line_length = 120

[*.{xml,html}]
indent_style = space
indent_size = 4

[*.{yaml,yml}]
indent_style = space
indent_size = 2

[*.{json,js}]
indent_style = space
indent_size = 4

[*.{css,scss}]
indent_style = space
indent_size = 4

[Makefile]
indent_style = tab

[{composer.json,package.json}]
indent_style = space
indent_size = 4

3. PhpStorm and EditorConfig: automatic adoption

PhpStorm has supported EditorConfig natively since version 2019.2, no plugin required. As soon as an .editorconfig file exists in the project, PhpStorm automatically adopts the rules defined in it and shows in the status bar which EditorConfig rules apply to the current file. This means: code style settings in the PhpStorm UI have no effect on files covered by EditorConfig, EditorConfig takes precedence.

The PhpStorm EditorConfig plugin can be enabled or disabled under Settings → Editor → Code Style. When active, an EditorConfig indicator appears in the lower status bar. Clicking it opens the responsible .editorconfig file directly in the editor. This is especially useful in projects with several nested .editorconfig files, to quickly trace which rules apply to a given file.

PhpStorm checks the complete EditorConfig hierarchy when opening a file, from the file in the current directory up to the root marker. Conflicts between PhpStorm's code style settings and EditorConfig are generally resolved clearly in favor of EditorConfig. For teams, it's recommended to check the code style XML files under .idea/codeStyles/ into the repository so that PhpStorm-specific settings stay aligned with the EditorConfig rules.

4. Configuring PHP code style in PhpStorm

Under Settings → Editor → Code Style → PHP you'll find the complete PhpStorm PHP formatting configuration. Here you can configure indentation, spacing around operators, bracket placement, line wrapping for long method signatures and much more. For Magento 2 projects, using the PSR-12 preset, loaded via "Set from → PSR-12", is recommended. This preset matches the Magento 2 coding standard and is directly compatible with PHP_CodeSniffer rules.

PhpStorm lets you export the configured code style as an XML file. This file can be placed in the .idea/codeStyles/ directory and checked in. When other developers open the project, PhpStorm automatically adopts the shared code style. Under Settings → Editor → Code Style you can distinguish between "Project" (shared, in the repo) and "IDE" (local). For team consistency, "Project" should always be used.

Particularly relevant for PHP 8.x projects: PhpStorm knows the formatting rules for constructor property promotion, named arguments, match expressions and fibers. These can be configured in fine detail under the PHP-specific code style settings. For Magento 2 with PHP 8.4, it's recommended to format constructor property promotion without extra indentation and to always wrap named arguments onto new lines whenever they exceed the maximum line length.

5. Integrating PHP CS Fixer into PhpStorm

PHP CS Fixer is a tool that automatically formats PHP code according to configured rules, not merely checking it but directly correcting it. The integration into PhpStorm runs via Settings → PHP → Quality Tools → PHP CS Fixer. There you enter the path to the binary (for Docker: the container path via the remote interpreter) and confirm the connection. PHP CS Fixer then appears as an option under External Tools and can be applied to the current file or the entire project via the code menu or a keyboard shortcut.

The rule configuration happens in a .php-cs-fixer.php file at the project root. For Magento 2 with PSR-12 and PHP 8.x, the rule sets @PSR12, @PHP80Migration and selected individual rules such as array_syntax (short array syntax), ordered_imports, no_unused_imports and declare_strict_types are recommended. This file is checked in and applies equally to every developer and the CI pipeline.

A common pitfall: PHP CS Fixer sometimes changes code that PHP_CodeSniffer then still flags as a violation, because the two tools have slightly different interpretations of the PSR-12 rules. The solution is to use PHP CS Fixer as the primary formatting tool and PHP_CodeSniffer only for inspections, not for autofixes. That way the tools complement each other without conflicts.

<?php
// .php-cs-fixer.php (Magento 2 / Hyvä with PHP 8.4)
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$finder = Finder::create()
    ->in(__DIR__ . '/app/code')
    ->in(__DIR__ . '/app/design')
    ->name('*.php')
    ->notPath('vendor')
    ->notPath('generated');

return (new Config())
    ->setRules([
        '@PSR12'                   => true,
        '@PHP84Migration'          => true,
        'array_syntax'             => ['syntax' => 'short'],
        'ordered_imports'          => ['sort_algorithm' => 'alpha'],
        'no_unused_imports'        => true,
        'declare_strict_types'     => true,
        'single_quote'             => true,
        'trailing_comma_in_multiline' => true,
        'phpdoc_align'             => ['align' => 'left'],
        'phpdoc_no_empty_return'   => true,
        'binary_operator_spaces'   => ['default' => 'single_space'],
        'blank_line_before_statement' => ['statements' => ['return', 'throw', 'try']],
    ])
    ->setFinder($finder)
    ->setUsingCache(true)
    ->setCacheFile(__DIR__ . '/.php-cs-fixer.cache');

6. Setting up PHP_CodeSniffer for Magento 2 standards

PHP_CodeSniffer (phpcs) checks PHP code against a defined standard, it doesn't format automatically, it reports violations. For Magento 2 there's the official Magento2 standard in the magento/magento-coding-standard package. After installing it via Composer, you register the standard and set up PhpStorm under Settings → PHP → Quality Tools → PHP_CodeSniffer. The inspections then appear directly in the editor as yellow or red underlines.

Configuring the Magento standard via a phpcs.xml file at the project root allows adjusting rules for the specific project. Common adjustments: disabling certain sniffs that aren't relevant for a Hyvä theme (e.g. Knockout.js-related rules), or excluding file paths from the check (e.g. generated/, pub/). The phpcs.xml is checked in and applies to every developer and the CI pipeline.

PhpStorm shows phpcs violations directly while typing when real-time inspection is enabled. For large codebases this can slow the IDE down, in that case it's recommended to run the phpcs inspection only on save or manually. The configuration is found under Settings → Editor → Inspections → PHP → PHP_CodeSniffer. There you can also set from which severity level problems are highlighted.

7. Configuring PhpStorm inspections deliberately

PhpStorm ships with over 600 built-in inspections for PHP that detect potential bugs, type problems, deprecated syntax and code smells. Under Settings → Editor → Inspections → PHP every inspection can be toggled on and off and its severity adjusted. Particularly relevant for PHP 8.4 projects: the inspections for deprecated functions, undeclared types, missing return types and unused variables. These surface problems before PHPStan or CI pipelines report them.

Inspection profiles can be exported and checked into the repository. Under Settings → Editor → Inspections a profile can be exported as XML. When the profile lives under .idea/inspectionProfiles/ and is checked in, every team member automatically uses the same profile. That ensures no developer unknowingly works with disabled inspections that would flag problems for others.

Integrating PHPStan is a further step: the PHPStan plugin for PhpStorm shows PHPStan errors directly in the editor, in sync with typing or on save. For Magento 2 with the bitexpert/phpstan-magento extension package, PHPStan correctly recognizes Magento-specific patterns such as factory injections, ObjectManager calls and magic methods. The configuration in the phpstan.neon file is read by both PhpStorm and the CI pipeline.

8. Save Actions: automatic formatting on save

The "Save Actions" plugin (or the "Actions on Save" feature built into newer PhpStorm versions) automatically runs defined actions when a file is saved. Under Settings → Tools → Actions on Save you can enable: "Reformat code" (applies the configured code style), "Optimize imports" (removes unused use statements and sorts them), "Run code cleanup" (runs quick fixes for known inspection issues) and "Run PHP CS Fixer" (when configured as an external tool).

The combination of "Reformat code" and "Optimize imports" as a save action is especially valuable in Magento 2 projects. After writing new code, you no longer need to remember to format manually, it happens automatically on save. That also means: commits no longer contain accidental formatting changes, because every file is formatted consistently on save.

Important: "Reformat code" as a save action only affects the code style configured in PhpStorm, not PHP CS Fixer rules. Anyone using both should make sure the PHP CS Fixer rules and the PhpStorm code style are compatible. The simplest solution: set the PhpStorm code style to PSR-12 and configure PHP CS Fixer with @PSR12 as well. That way both tools are configured with the same baseline rules.

<?php
// PhpStorm Code Style XML (project-shared configuration)
// Stored in .idea/codeStyles/Project.xml (check into repository)

/*
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
  <component name="ProjectCodeStyleConfiguration">
    <code_scheme name="Project" version="173">
      <PHPCodeStyleSettings>
        <option name="ALIGN_KEY_VALUE_PAIRS" value="false" />
        <option name="ALIGN_PHPDOC_COMMENTS" value="false" />
        <option name="FORCE_SHORT_DECLARATION_ARRAY_STYLE" value="true" />
        <option name="SPACES_WITHIN_SHORT_ARRAY" value="false" />
        <option name="KEEP_RPAREN_AND_LBRACE_ON_ONE_LINE" value="true" />
        <option name="BLANK_LINES_AROUND_METHOD" value="1" />
        <option name="BLANK_LINE_BEFORE_RETURN_STATEMENT" value="false" />
      </PHPCodeStyleSettings>
      <codeStyleSettings language="PHP">
        <option name="RIGHT_MARGIN" value="120" />
        <option name="INDENT_SIZE" value="4" />
        <option name="TAB_SIZE" value="4" />
        <option name="USE_TAB_CHARACTER" value="false" />
      </codeStyleSettings>
    </code_scheme>
  </component>
</project>
*/

// Verify consistent formatting across tools:
// bin/phpcs --standard=phpcs.xml app/code/
// bin/phpcbf --standard=phpcs.xml app/code/
// vendor/bin/php-cs-fixer fix --dry-run --diff app/code/

9. Tool comparison: which tool covers what?

The four tools EditorConfig, PHP CS Fixer, PHP_CodeSniffer and PhpStorm inspections have different responsibilities. A clear separation avoids conflicts and ensures each tool does what it does best.

The recommended layering for Magento 2 / Hyvä projects: EditorConfig as the baseline for every file type and every editor. PHP CS Fixer for automatic formatting as a save action in PhpStorm and in the CI pipeline (--dry-run --diff). PHP_CodeSniffer for the Magento 2 coding standard as a PhpStorm inspection and CI check. PHPStan (level 5 to 8) for type analysis as a PhpStorm plugin and its own CI job. This combination covers every quality dimension without tools clashing.

10. Summary

Team consistency in code isn't a cultural problem, it's a tooling problem. EditorConfig secures baseline formatting for every editor and prevents whitespace conflicts in diffs. PHP CS Fixer automatically formats PHP code per PSR-12 and project-specific rules, as a save action in PhpStorm and as a CI check with --dry-run. PHP_CodeSniffer checks the Magento 2 coding standard and shows violations in PhpStorm as inspections. PhpStorm inspections and PHPStan round out the picture with type analysis and code smells.

The decisive investment is setting up these tools correctly once and checking all configuration files into the repository. Anyone who has .editorconfig, .php-cs-fixer.php, phpcs.xml, phpstan.neon and the .idea/codeStyles/ configuration in the repo ensures that every new developer works with the same standards from day one, with no elaborate onboarding needed.

11. FAQ: EditorConfig and Code Style in PhpStorm