Run Configurations in PhpStorm für PHPUnit, Magento CLI und Custom Commands

1. Warum Run Configurations mehr sind als ein Terminal-Ersatz

Run Configurations in PhpStorm sind keine vereinfachten Terminal-Shortcuts. Sie sind vollständig parametrisierbare Ausführungskontexte, die Interpreter, Arbeitsverzeichnis, Umgebungsvariablen, Before-Launch-Tasks und Debugging-Integration in einem einzigen, wiederverwendbaren Profil zusammenfassen. Wer im Entwicklungsalltag Magento-CLI-Befehle tippt, muss sich jedes Mal an Syntax, Pfade und Docker-Wrapper erinnern. Mit einer Run Configuration reduziert sich das auf einen Tastendruck – und der Ablauf ist immer korrekt und reproduzierbar.

Der entscheidende Unterschied zum Terminal liegt in der Xdebug-Integration. Ein PHPUnit-Test, der als Run Configuration ausgeführt wird, kann mit dem grünen Debug-Button gestartet werden – PhpStorm hält an jedem Breakpoint an, zeigt den Call Stack, die aktuellen Variablenwerte und erlaubt Step-through-Debugging. Für Tests, die im Terminal laufen, ist das ohne manuelle XDEBUG_MODE-Konfiguration nicht möglich. Run Configurations abstrahieren diese Komplexität vollständig weg.

Für Teams ist der größte Vorteil die Shareability. Run Configurations können als XML-Dateien im .idea/runConfigurations/-Verzeichnis versioniert werden. Jeder Entwickler hat nach einem git clone sofort alle Konfigurationen verfügbar – keine README-Anleitung, kein Kopieren von Befehlen, keine Fehler durch leicht unterschiedliche Terminal-Setups. Das allein rechtfertigt die einmalige Investition in sauber aufgesetzte Run Configurations.

2. Grundstruktur einer Run Configuration verstehen

PhpStorm kennt verschiedene Run Configuration Typen, die sich in ihrer Zieldomäne unterscheiden: PHP Script für direkte PHP-Dateien, PHPUnit für Test-Runner, Shell Script für Bash-Skripte und Compound für das sequenzielle oder parallele Ausführen mehrerer Konfigurationen. Jeder Typ hat gemeinsame Grundfelder: Name, Interpreter (lokal oder remote), Arbeitsverzeichnis und Umgebungsvariablen.

Der Interpreter ist das zentrale Element jeder PHP-basierten Run Configuration. In einer Docker-Umgebung nach dem Mark-Shust-Pattern läuft PHP im Container, nicht auf dem Host. PhpStorm erlaubt es, einen Remote-Interpreter zu definieren, der über Docker, Docker Compose oder SSH kommuniziert. Sobald dieser Interpreter eingerichtet ist, verwenden alle Run Configurations, die auf ihn verweisen, automatisch die PHP-Version und die PHP-Extensions des Containers – identisch zur Produktionsumgebung.

Das Arbeitsverzeichnis einer Run Configuration bestimmt, von wo aus relative Pfade aufgelöst werden. Für Magento-Projekte ist das immer das Magento-Root-Verzeichnis im Container – typischerweise /var/www/html. Ist das falsch gesetzt, schlagen Autoloader und Konfigurationspfade still fehl. Beim erstmaligen Einrichten einer Run Configuration sollte man das Arbeitsverzeichnis daher immer explizit angeben, nie auf den Default vertrauen.

3. PHPUnit-Konfiguration mit Docker-Remote-Interpreter

Eine PHPUnit Run Configuration für Magento mit Docker erfordert drei Voraussetzungen: einen konfigurierten Remote-Interpreter, eine phpunit.xml-Datei im Projektverzeichnis und den PHPUnit-Autoloader. In PhpStorm öffnet man Run → Edit Configurations → + → PHPUnit. Als Interpreter wählt man den Docker-Interpreter, der auf den phpfpm-Service des Magento-Compose-Stacks zeigt. Der Test-Scope kann auf eine einzelne Klasse, ein Verzeichnis oder die komplette phpunit.xml-Konfiguration gesetzt werden.

Die phpunit.xml für Magento-Integration-Tests zeigt dabei auf Magento's Bootstrap-Datei. Das ist der häufigste Fehler beim Setup: PHPUnit findet den Bootstrap nicht, weil der Pfad relativ zum Host statt zum Container-Dateisystem angegeben ist. Mit einem Remote-Interpreter werden alle Pfade in der phpunit.xml als Container-Pfade interpretiert. Das bedeutet, dass die XML-Datei Container-Pfade (/var/www/html/dev/tests/...) verwenden muss, nicht Host-Pfade.

<!-- phpunit.xml für Magento 2 Unit Tests in PhpStorm mit Docker-Interpreter -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
    bootstrap="/var/www/html/app/autoload.php"
    cacheDirectory="/var/www/html/var/.phpunit.cache"
    colors="true">

    <testsuites>
        <testsuite name="Mironsoft Unit Tests">
            <directory>/var/www/html/app/code/Mironsoft/*/Test/Unit</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory>/var/www/html/app/code/Mironsoft</directory>
        </include>
        <exclude>
            <directory>/var/www/html/app/code/Mironsoft/*/Test</directory>
        </exclude>
    </source>

    <php>
        <env name="MAGENTO_FRAMEWORK_MODULE_PATH"
             value="/var/www/html/vendor/magento/framework"/>
    </php>
</phpunit>

Sobald die Run Configuration gespeichert ist, erscheint sie im Run-Dropdown oben rechts. Mit Ctrl+Shift+F10 wird die Run Configuration der aktuell geöffneten Test-Datei gestartet. PhpStorm erkennt PHPUnit-Testklassen und blendet in der Seitenleiste grüne Run-Icons neben jeder Testmethode ein – ein Klick startet genau diesen einen Test. Das spart erheblich Zeit gegenüber dem Ausführen der gesamten Test-Suite.

4. Magento CLI-Befehle als Run Configuration

Magento-CLI-Befehle wie setup:upgrade, cache:flush oder Custom-Commands eigener Module lassen sich als PHP Script-Run-Configurations hinterlegen. Der Trick liegt darin, als PHP-Datei nicht ein eigenes Skript, sondern bin/magento anzugeben und den gewünschten Befehl als Argument mitzugeben. Mit dem Docker-Remote-Interpreter läuft der Befehl direkt im Container – genau wie bin/magento cache:flush im Terminal, aber ohne das Terminal zu öffnen.

Für häufig genutzte Befehle empfiehlt sich eine Sammlung benannter Run Configurations: Magento: Cache Flush, Magento: Setup Upgrade, Magento: DI Compile. Diese können über Run → Run… oder den Shortcut Alt+Shift+F10 aufgelistet und mit einem Tastendruck gestartet werden. Besonders praktisch ist die Option, verschiedene Konfigurationen mit unterschiedlichen --env-Argumenten zu erstellen – etwa einen separaten Run für setup:static-content:deploy de_DE mit dem -f-Flag.

<?php
// .idea/runConfigurations/Magento_Cache_Flush.xml
// Diese Datei wird von PhpStorm automatisch gelesen und als Run Configuration angezeigt.
// Versionskontrolle: Diese Datei ins Git-Repository einchecken!

/*
<component name="ProjectRunConfigurationManager">
  <configuration default="false"
                 name="Magento: Cache Flush"
                 type="PhpScriptRunConfigurationType"
                 factoryName="PHP Script">
    <option name="path" value="$PROJECT_DIR$/src/bin/magento" />
    <option name="arguments" value="cache:flush" />
    <option name="workingDirectory" value="$PROJECT_DIR$/src" />
    <method v="2">
      <option name="com.jetbrains.php.run.script.PhpScriptBeforeLaunchTask"
              enabled="false" />
    </method>
  </configuration>
</component>
*/

5. Umgebungsvariablen und Secrets sicher verwalten

Run Configurations unterstützen Umgebungsvariablen auf zwei Arten: direkt im Konfigurationsdialog unter Environment variables oder über eine .env-Datei, die PhpStorm einliest. Für Secrets wie Datenbankpasswörter oder API-Keys ist die direkte Eingabe im Dialog problematisch – die Werte werden in der XML-Konfigurationsdatei gespeichert, die im Repository landet. Der sichere Weg ist die Verwendung von Platzhaltern, die auf System-Umgebungsvariablen verweisen: $DB_PASSWORD wird zur Laufzeit durch den Wert aus der Shell-Session ersetzt.

PhpStorm unterstützt seit Version 2023.1 die direkte Integration von .env-Dateien. Im Run Configuration Dialog kann unter Environment variables → … eine .env-Datei angegeben werden. Diese Datei sollte in .gitignore stehen und nur lokal existieren. Das Pattern ist identisch zu dem, was Docker Compose für env_file-Einträge nutzt – wer seine Docker-Compose-Umgebungsvariablen bereits in einer .env-Datei verwaltet, kann dieselbe Datei in Run Configurations verwenden.

Eine saubere Struktur für Magento-Projekte: Eine env/phpstorm.env-Datei enthält alle Werte, die Run Configurations benötigen – Datenbankverbindung, Magento-Basis-URL und Debug-Flags. Diese Datei steht in .gitignore. Im Repository liegt eine env/phpstorm.env.example als Vorlage mit Dummy-Werten. Neue Entwickler kopieren die Datei, passen Werte an und alle Run Configurations funktionieren sofort ohne manuelle Anpassung.

6. Compound Run Configurations für komplexe Abläufe

Compound Run Configurations kombinieren mehrere einzelne Konfigurationen und starten sie entweder sequenziell oder parallel. Das typische Use Case für Magento: Deploy-Sequence als Compound, das zunächst Magento: DI Compile, dann Magento: Setup Upgrade und schließlich Magento: Cache Flush ausführt. Statt drei separate Befehle im Terminal zu tippen oder ein Shell-Skript aufzurufen, reicht ein Klick – und PhpStorm zeigt den Output jedes Schritts übersichtlich in eigenen Tabs.

Compound Configurations sind besonders wertvoll für Test-Setups. Eine All Tests-Konfiguration kann Unit-Tests und Integration-Tests parallel starten und am Ende beide Ergebnisse anzeigen. PhpStorm aggregiert die Testergebnisse nicht, aber jeder Run hat seinen eigenen Output-Tab. Wenn einer der Runs fehlschlägt, ist sofort erkennbar, welche Konfiguration verantwortlich ist, ohne die Ausgabe zu durchsuchen.

7. Shell Script Configurations und Before-Launch-Tasks

PhpStorm unterstützt neben PHP-Konfigurationen auch Shell Script Configurations. Damit lassen sich Bash-Skripte – etwa bin/cache-clean oder eigene Deploy-Wrapper – direkt aus der IDE starten. Die Konfiguration erfolgt unter + → Shell Script. Als Interpreter kann /bin/bash angegeben werden, als Script-Path der absolute Pfad zum Skript. Für Docker-basierte Setups mit dem Mark-Shust-Pattern ist das ideal: Die bin/-Wrapper-Skripte, die Befehle im Container ausführen, können als Shell-Konfigurationen hinterlegt werden.

Before-Launch-Tasks ermöglichen es, vor dem Hauptrun eine weitere Konfiguration zu starten. Praktisch für Test-Runs: Vor dem PHPUnit-Run wird automatisch ein Magento: Cache Clean-Task ausgeführt, um einen sauberen Ausgangszustand sicherzustellen. Die Before-Launch-Tasks werden im Konfigurationsdialog unten konfiguriert – mit dem Plus-Icon können beliebig viele Tasks hinzugefügt werden. Auch externe Tools wie composer install oder CSS-Build-Prozesse lassen sich als Before-Launch-Tasks einbinden.

<?php
// Beispiel: Eigener Magento-CLI-Command als Run Configuration-Ziel
// app/code/Mironsoft/Catalog/Console/Command/SyncProducts.php

declare(strict_types=1);

namespace Mironsoft\Catalog\Console\Command;

use Magento\Framework\Console\Cli;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Console command to sync product data from external source.
 * Run via PhpStorm: bin/magento mironsoft:catalog:sync-products --limit=100
 */
final class SyncProducts extends Command
{
    private const OPTION_LIMIT = 'limit';

    public function __construct(
        private readonly \Mironsoft\Catalog\Api\ProductSyncServiceInterface $syncService,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setName('mironsoft:catalog:sync-products')
            ->setDescription('Sync products from external catalog API')
            ->addOption(self::OPTION_LIMIT, null, InputOption::VALUE_OPTIONAL, 'Max products to sync', 500);
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $limit = (int) $input->getOption(self::OPTION_LIMIT);
        $output->writeln(sprintf('<info>Syncing up to %d products...</info>', $limit));
        $synced = $this->syncService->sync($limit);
        $output->writeln(sprintf('<info>Done. Synced: %d</info>', $synced));
        return Cli::RETURN_SUCCESS;
    }
}

8. Direkt in die Run Configuration debuggen

Das Debugging über Run Configurations ist der stärkste Vorteil gegenüber dem Terminal. Statt XDEBUG_MODE=debug php bin/magento ... manuell zu setzen, reicht es, den Debug-Button (grünes Käfer-Icon) statt des Run-Buttons zu klicken. PhpStorm setzt automatisch die nötigen Xdebug-Umgebungsvariablen für den Remote-Interpreter und wartet auf die Verbindung. Breakpoints in beliebigen PHP-Dateien – inklusive Magento-Core-Dateien im vendor/-Verzeichnis – werden zuverlässig getroffen.

Für PHPUnit-Debugging ist das besonders wertvoll. Ein Test, der einen unerwarteten Fehler produziert, lässt sich durch einen einzigen Debug-Run schrittweise durchgehen. Der Call Stack zeigt genau, welche Methoden in welcher Reihenfolge aufgerufen wurden. Variableninspektionen offenbaren den genauen Zustand des Objekts zum Zeitpunkt des Fehlers – ohne dass ein einziger var_dump in den Code eingefügt werden muss. Das reduziert den Debugging-Zyklus von Minuten auf Sekunden.

9. Run Configuration Typen im Vergleich

Die Wahl des richtigen Run Configuration Typs ist entscheidend für die Funktionalität. Jeder Typ bietet andere Optionen und eignet sich für unterschiedliche Szenarien im Magento-Entwicklungsalltag.

Für Magento-Projekte sind die PHPUnit- und PHP-Script-Typen am wichtigsten. Sie profitieren vollständig vom Remote-Interpreter und der Xdebug-Integration. Shell-Script-Konfigurationen sind nützlich für Build-Prozesse, die außerhalb des PHP-Containers laufen – etwa der Tailwind-CSS-Build-Prozess. Compound-Konfigurationen bündeln alles zu einem One-Click-Workflow.

10. Zusammenfassung

Run Configurations in PhpStorm sind das Bindeglied zwischen der IDE und dem laufenden Magento-Docker-Stack. Mit einem korrekt konfigurierten Remote-Interpreter können PHPUnit-Tests mit einem Tastendruck gestartet und debuggt werden. Magento-CLI-Befehle werden als PHP-Script-Konfigurationen hinterlegt und müssen nie wieder im Terminal getippt werden. Compound-Konfigurationen bündeln Deploy-Abläufe zu reproduzierbaren Ein-Klick-Workflows.

Der wichtigste Schritt ist die Versionierung der Konfigurationen. Die XML-Dateien im .idea/runConfigurations/-Verzeichnis ins Repository einzuchecken stellt sicher, dass alle Entwickler denselben Ausgangszustand haben. Umgebungsvariablen und Secrets bleiben über .env-Dateien lokal, die Konfigurationsstruktur selbst wird geteilt. Das Ergebnis ist ein IDE-Setup, das neue Teammitglieder nach einem einzigen git clone produktiv einsetzt.

11. FAQ: Run Configurations in PhpStorm