EditorConfig, Code Style und Teamkonsistenz in PhpStorm

1. Das Teamkonsistenz-Problem und warum es Tooling braucht

In jedem Team mit mehr als einer Person entsteht dasselbe Muster: Entwickler A bevorzugt Tabs, Entwickler B Spaces. Die IDE von C formatiert Klammern anders als die von D. Das Ergebnis sind Diffs, in denen Whitespace-Änderungen die eigentlichen Code-Änderungen überlagern – Git-Blame wird unbrauchbar, Code-Reviews länger. Diese Probleme sind nicht durch Coding-Guidelines allein lösbar, weil sie manuell nicht konsistent durchgesetzt werden können.

Die Lösung liegt in drei Schichten von Tooling, die ineinandergreifen: EditorConfig stellt sicher, dass Basis-Formatierung wie Einrückung und Zeilenenden in jedem Editor gleich behandelt wird. PHP CS Fixer oder PHP_CodeSniffer formatieren und prüfen PHP-Dateien nach definierten Regeln. PhpStorm-Inspektionen heben Code-Qualitätsprobleme direkt beim Schreiben hervor, bevor der Code überhaupt committed wird. Zusammen bilden diese Schichten ein automatisiertes Qualitätsnetz.

Die Kosten für fehlende Konsistenz sind konkret messbar: Whitespace-Diffs erhöhen den Review-Aufwand, inkonsistente Formatierung verlangsamt das Lesen fremden Codes, und unterschiedliche Standards zwischen IDE-Konfigurationen führen dazu, dass Code nach einem Formatierungs-Commit von jemandem anderen sofort wieder durch die eigene IDE-Formatierung verändert wird. Tooling-basierte Konsistenz löst diese Probleme einmal und dauerhaft.

2. EditorConfig: die Basis-Ebene für alle Editoren

Eine .editorconfig-Datei im Projektstamm ist der kleinste gemeinsame Nenner für alle Editoren – PhpStorm, VS Code, Vim, Emacs. Sie definiert grundlegende Formatierungsregeln wie Einrückungsart (indent_style = space), Einrückungstiefe (indent_size = 4), Zeilenenden (end_of_line = lf), Zeichensatz (charset = utf-8) und ob Leerzeichen am Zeilenende entfernt werden sollen (trim_trailing_whitespace = true). Diese Datei wird ins Repository eingecheckt und gilt für alle Teammitglieder unabhängig von ihrer IDE.

Für PHP-Projekte – insbesondere Magento 2 nach PSR-2 und PSR-12 – empfiehlt sich eine .editorconfig, die PHP-Dateien explizit mit 4 Spaces konfiguriert, aber für YAML-, JSON- und andere Dateitypen eigene Regeln definiert. Magento 2 nutzt zum Beispiel 4 Spaces für PHP, aber 2 Spaces für XML-Layout-Dateien. EditorConfig unterstützt dateiendungsspezifische Sektionen mit Glob-Patterns wie [*.{php,phtml}] und [*.xml].

Ein oft übersehenes Detail: Die root = true-Angabe am Dateianfang verhindert, dass EditorConfig nach übergeordneten .editorconfig-Dateien sucht. Ohne diese Angabe kann eine .editorconfig im Home-Verzeichnis des Entwicklers die Projektregeln überschreiben. In Monorepo-Setups mit mehreren Projekten in Unterverzeichnissen kann jedes Unterverzeichnis eine eigene .editorconfig haben, die die Elternregeln für ihren Bereich überschreibt.

# .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 und EditorConfig: automatische Übernahme

PhpStorm unterstützt EditorConfig nativ seit Version 2019.2 – ohne Plugin. Sobald eine .editorconfig-Datei im Projekt vorhanden ist, übernimmt PhpStorm die darin definierten Regeln automatisch und zeigt in der Statusleiste an, welche EditorConfig-Regeln für die aktuelle Datei gelten. Das bedeutet: Code-Style-Einstellungen in der PhpStorm-UI haben für Dateien, die von EditorConfig abgedeckt sind, keine Wirkung – EditorConfig hat Vorrang.

Das PhpStorm EditorConfig-Plugin kann in den Settings unter Settings → Editor → Code Style aktiviert oder deaktiviert werden. Wenn es aktiv ist, erscheint in der unteren Statusleiste ein EditorConfig-Indikator. Ein Klick darauf öffnet die zuständige .editorconfig-Datei direkt im Editor. Das ist besonders nützlich in Projekten mit mehreren verschachtelten .editorconfig-Dateien, um schnell nachzuvollziehen, welche Regeln für eine bestimmte Datei gelten.

PhpStorm überprüft beim Öffnen einer Datei die komplette EditorConfig-Hierarchie – von der Datei im aktuellen Verzeichnis bis zum Root-Marker. Konflikte zwischen den PhpStorm Code-Style-Einstellungen und der EditorConfig werden in der Regel klar zugunsten der EditorConfig aufgelöst. Für Teams empfiehlt sich, die Code-Style-XML-Dateien unter .idea/codeStyles/ ins Repository einzuchecken, damit die PhpStorm-spezifischen Einstellungen mit den EditorConfig-Regeln übereinstimmen.

4. PHP Code Style in PhpStorm konfigurieren

Unter Settings → Editor → Code Style → PHP findet sich die vollständige PhpStorm-PHP-Formatierungskonfiguration. Hier lassen sich Einrückung, Leerzeichen um Operatoren, Klammerplatzierung, Zeilenumbrüche bei langen Methodensignaturen und vieles mehr konfigurieren. Für Magento 2-Projekte empfiehlt sich die Nutzung des PSR-12-Presets, das unter "Set from → PSR-12" geladen wird. Dieses Preset entspricht dem Magento 2 Coding Standard und ist direkt mit PHP_CodeSniffer-Regeln kompatibel.

PhpStorm erlaubt das Exportieren des konfigurierten Code Styles als XML-Datei. Diese Datei kann ins .idea/codeStyles/-Verzeichnis gelegt und eingecheckt werden. Wenn andere Entwickler das Projekt öffnen, übernimmt PhpStorm automatisch den geteilten Code Style. Unter Settings → Editor → Code Style kann zwischen "Project" (geteilt, im Repo) und "IDE" (lokal) unterschieden werden. Für Teamkonsistenz sollte immer "Project" verwendet werden.

Besonders relevant für PHP 8.x-Projekte: PhpStorm kennt die Formatierungsregeln für Constructor Property Promotion, Named Arguments, Match-Expressions und Fibers. Diese können unter den PHP-spezifischen Code-Style-Einstellungen feingranular konfiguriert werden. Für Magento 2 mit PHP 8.4 empfiehlt sich, Constructor Property Promotion ohne zusätzliche Einrückung zu formatieren und Named Arguments immer auf neue Zeilen zu umbrechen, wenn sie die maximale Zeilenlänge überschreiten.

5. PHP CS Fixer in PhpStorm integrieren

PHP CS Fixer ist ein Tool, das PHP-Code automatisch nach konfigurierten Regeln formatiert – nicht nur prüft, sondern direkt korrigiert. Die Integration in PhpStorm läuft über Settings → PHP → Quality Tools → PHP CS Fixer. Dort trägt man den Pfad zum Binary ein (für Docker: den Container-Pfad via Remote-Interpreter) und bestätigt die Verbindung. PHP CS Fixer erscheint dann als Option unter External Tools und kann über das Code-Menü oder ein Tastenkürzel auf die aktuelle Datei oder das gesamte Projekt angewendet werden.

Die Regelkonfiguration erfolgt in einer .php-cs-fixer.php-Datei im Projektstamm. Für Magento 2 mit PSR-12 und PHP 8.x empfehlen sich die Regelgruppen @PSR12, @PHP80Migration und ausgewählte einzelne Regeln wie array_syntax (short array syntax), ordered_imports, no_unused_imports und declare_strict_types. Diese Datei wird eingecheckt und gilt für alle Entwickler und die CI-Pipeline gleichermaßen.

Ein häufiger Stolperstein: PHP CS Fixer ändert manchmal Code, den PHP_CodeSniffer danach noch als Verstoß meldet, weil die beiden Tools leicht unterschiedliche Interpretationen der PSR-12-Regeln haben. Die Lösung ist, PHP CS Fixer als primäres Formatierungstool zu nutzen und PHP_CodeSniffer nur für Inspektionen zu verwenden – nicht für Autofixes. So ergänzen sich die Tools ohne Konflikte.

<?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. PHP_CodeSniffer für Magento 2 Standards einrichten

PHP_CodeSniffer (phpcs) prüft PHP-Code gegen einen definierten Standard – es formatiert nicht automatisch, sondern meldet Verstöße. Für Magento 2 gibt es den offiziellen Magento2-Standard im Package magento/magento-coding-standard. Nach Installation via Composer registriert man den Standard und richtet PhpStorm unter Settings → PHP → Quality Tools → PHP_CodeSniffer ein. Die Inspektionen erscheinen dann direkt im Editor als gelbe oder rote Unterstreichungen.

Die Konfiguration des Magento-Standards über eine phpcs.xml-Datei im Projektstamm erlaubt das Anpassen von Regeln für das spezifische Projekt. Häufige Anpassungen: bestimmte Sniffs deaktivieren, die für ein Hyvä-Theme nicht relevant sind (z.B. Knockout.js-bezogene Regeln), oder Dateipfade aus der Prüfung ausschließen (z.B. generated/, pub/). Die phpcs.xml wird eingecheckt und gilt für alle Entwickler und die CI-Pipeline.

PhpStorm zeigt phpcs-Verstöße direkt beim Tippen an, wenn die Real-time-Inspektion aktiviert ist. Für große Codebasen kann das die IDE verlangsamen – in diesem Fall empfiehlt sich, die phpcs-Inspektion nur beim Speichern oder manuell auszuführen. Die Konfiguration findet sich unter Settings → Editor → Inspections → PHP → PHP_CodeSniffer. Dort lässt sich auch einstellen, ab welchem Severity-Level Probleme hervorgehoben werden.

7. PhpStorm-Inspektionen gezielt konfigurieren

PhpStorm bringt über 600 eingebaute Inspektionen für PHP mit, die potenzielle Fehler, Typprobleme, veraltete Syntax und Code-Smells erkennen. Unter Settings → Editor → Inspections → PHP können alle Inspektionen ein- und ausgeschaltet sowie in ihrer Severity angepasst werden. Für PHP 8.4-Projekte besonders relevant: die Inspektionen für deprecated Funktionen, undeclared types, fehlende return types und nicht genutzte Variablen. Diese heben Probleme hervor, bevor PHPStan oder CI-Pipelines sie melden.

Inspektionsprofile lassen sich exportieren und ins Repository einchecken. Unter Settings → Editor → Inspections kann ein Profil als XML exportiert werden. Wenn das Profil unter .idea/inspectionProfiles/ liegt und eingecheckt ist, verwenden alle Teammitglieder automatisch dasselbe Profil. Das stellt sicher, dass ein Entwickler nicht unwissentlich mit deaktivierten Inspektionen arbeitet, die anderen Problemen aufdecken würden.

Die Integration mit PHPStan ist ein weiterer Schritt: Das PHPStan-Plugin für PhpStorm zeigt PHPStan-Fehler direkt im Editor an, synchron mit dem Tippen oder beim Speichern. Für Magento 2 mit dem bitexpert/phpstan-magento-Extension-Package erkennt PHPStan Magento-spezifische Muster wie Factory-Injektionen, ObjectManager-Aufrufe und magische Methoden korrekt. Die Konfiguration in der phpstan.neon-Datei wird sowohl von PhpStorm als auch von der CI-Pipeline gelesen.

8. Save Actions: automatische Formatierung beim Speichern

Das "Save Actions"-Plugin (oder die in neueren PhpStorm-Versionen eingebaute "Actions on Save"-Funktion) führt beim Speichern einer Datei automatisch definierte Aktionen aus. Unter Settings → Tools → Actions on Save können aktiviert werden: "Reformat code" (wendet den konfigurierten Code Style an), "Optimize imports" (entfernt ungenutzte Use-Statements und sortiert sie), "Run code cleanup" (führt Quick-Fixes für bekannte Inspektionsprobleme aus) und "Run PHP CS Fixer" (wenn als External Tool konfiguriert).

Die Kombination aus "Reformat code" und "Optimize imports" als Save Action ist in Magento 2-Projekten besonders wertvoll. Nach dem Schreiben von neuem Code muss man sich nicht mehr daran erinnern, manuell zu formatieren – das passiert automatisch beim Speichern. Das bedeutet auch: Commits enthalten keine zufälligen Formatierungsänderungen mehr, weil jede Datei beim Speichern konsistent formatiert wird.

Wichtig: "Reformat code" als Save Action wirkt nur auf den Code Style, der in PhpStorm konfiguriert ist – nicht auf PHP CS Fixer-Regeln. Wer beides nutzt, sollte sicherstellen, dass PHP CS Fixer-Regeln und PhpStorm Code Style kompatibel sind. Die einfachste Lösung: PhpStorm Code Style auf PSR-12 setzen und PHP CS Fixer ebenfalls auf @PSR12 konfigurieren. So sind beide Tools mit denselben Basis-Regeln konfiguriert.

<?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-Vergleich: Was übernimmt welches Werkzeug?

Die vier Tools EditorConfig, PHP CS Fixer, PHP_CodeSniffer und PhpStorm-Inspektionen haben unterschiedliche Verantwortlichkeiten. Eine klare Abgrenzung vermeidet Konflikte und stellt sicher, dass jedes Tool das tut, was es am besten kann.

Die empfohlene Schichtung für Magento 2 / Hyvä-Projekte: EditorConfig als Basis für alle Dateitypen und alle Editoren. PHP CS Fixer für automatische Formatierung als Save Action in PhpStorm und in der CI-Pipeline (--dry-run --diff). PHP_CodeSniffer für den Magento 2 Coding Standard als PhpStorm-Inspektion und CI-Check. PHPStan (Level 5–8) für Typ-Analysen als PhpStorm-Plugin und eigener CI-Job. Diese Kombination deckt alle Qualitätsdimensionen ab, ohne dass Tools in Konflikt geraten.

10. Zusammenfassung

Teamkonsistenz im Code ist kein kulturelles Problem, sondern ein Tooling-Problem. EditorConfig stellt die Basis-Formatierung für alle Editoren sicher und verhindert Whitespace-Konflikte in Diffs. PHP CS Fixer formatiert PHP-Code automatisch nach PSR-12 und projektspezifischen Regeln – als Save Action in PhpStorm und als CI-Check mit --dry-run. PHP_CodeSniffer prüft den Magento 2 Coding Standard und zeigt Verstöße in PhpStorm als Inspektionen an. PhpStorm-Inspektionen und PHPStan ergänzen das Bild mit Typ-Analysen und Code-Smells.

Die entscheidende Investition ist das Einrichten dieser Werkzeuge einmalig korrekt und das Einchecken aller Konfigurationsdateien ins Repository. Wer .editorconfig, .php-cs-fixer.php, phpcs.xml, phpstan.neon und die .idea/codeStyles/-Konfiguration im Repo hat, sorgt dafür, dass jeder neue Entwickler sofort mit denselben Standards arbeitet – ohne aufwändiges Onboarding.

11. FAQ: EditorConfig und Code Style in PhpStorm