HTTP Client Umgebungsdateien in PhpStorm: Private Variablen sicher verwalten

1. Warum Umgebungsdateien beim API-Testen ueberhaupt noetig sind

In jedem Magento-Projekt gibt es mindestens drei Umgebungen: eine lokale Docker-Instanz, ein Staging-System und die Produktion. Jede davon hat eine eigene Basis-URL, eigene Admin-Zugangsdaten und eigene Integration-Tokens. Wer diese Werte fest in die .http-Datei schreibt, muss bei jedem Umgebungswechsel den Request-Text manuell anfassen und riskiert, dass die Datei beim naechsten Commit die falschen oder gar geheime Werte enthaelt.

PhpStorm loest dieses Problem, indem es Variablen aus separaten JSON-Dateien in die Requests einspeist. Der Request selbst bleibt umgebungsunabhaengig, nur die aktuell aktive Umgebung entscheidet, welche konkreten Werte tatsaechlich verwendet werden. Fuer ein Magento-Team bedeutet das: dieselbe .http-Datei funktioniert gegen lokal, Staging und Produktion, ohne dass eine einzige Zeile im Request angepasst werden muss.

In der Praxis zeigt sich das besonders bei Magento-Projekten mit mehreren Stores und Websites, wo zusaetzlich noch store-spezifische Header wie Store oder Content-Currency korrekt gesetzt werden muessen. Ohne Umgebungsdateien landen solche Detailinformationen schnell verstreut in Kommentaren oder im Gedaechtnis einzelner Entwickler, statt zentral gepflegt zu werden.

2. Der Unterschied zwischen oeffentlicher und privater Umgebungsdatei

http-client.env.json ist fuer Werte gedacht, die im gesamten Team geteilt werden duerfen: Basis-URLs, Store-Codes, oeffentliche Endpunkt-Pfade oder die verwendete Zeitzone. Diese Datei liegt im Projektverzeichnis und wird ganz normal in Git eingecheckt, denn sie enthaelt nichts, was ein Angreifer verwerten koennte.

http-client.private.env.json dagegen ist fuer alles gedacht, das persoenlich oder geheim ist: Admin-Bearer-Token, persoenliche Integration-Keys, Datenbank-Passwoerter fuer lokale Testzwecke. PhpStorm erwartet diese Datei ebenfalls im Projektroot und fuehrt ihre Werte mit denen der oeffentlichen Datei zusammen. Wichtig ist, dass beide Dateien fuer dieselbe Umgebung denselben Schluessel verwenden, sonst werden die Werte nicht korrekt gemergt.

3. http-client.env.json: Struktur der oeffentlichen Datei

Die oeffentliche Datei definiert fuer jede Umgebung ein eigenes JSON-Objekt. Ueblich sind mindestens die Umgebungen local, staging und production, jede mit einer eigenen baseUrl und den Store-spezifischen Werten, die fuer Magento REST- oder GraphQL-Aufrufe gebraucht werden, etwa storeCode oder graphqlEndpoint.

Da diese Datei versioniert wird, sollte sie ausschliesslich Werte enthalten, die auch in einer oeffentlichen Dokumentation stehen koennten. Ein einfacher Test hilft bei der Entscheidung: Wuerde es etwas ausmachen, wenn diese Datei versehentlich oeffentlich im Internet einsehbar waere? Wenn die Antwort nein lautet, gehoert der Wert in diese Datei und nicht in die private Variante.

{
  "local": {
    "baseUrl": "https://mironsoft.test",
    "storeCode": "default",
    "graphqlEndpoint": "https://mironsoft.test/graphql",
    "timezone": "Europe/Berlin"
  },
  "staging": {
    "baseUrl": "https://staging.mironsoft.de",
    "storeCode": "default",
    "graphqlEndpoint": "https://staging.mironsoft.de/graphql",
    "timezone": "Europe/Berlin"
  },
  "production": {
    "baseUrl": "https://www.mironsoft.de",
    "storeCode": "default",
    "graphqlEndpoint": "https://www.mironsoft.de/graphql",
    "timezone": "Europe/Berlin"
  }
}

4. http-client.private.env.json: Struktur der privaten Datei

Die private Datei hat dieselbe grundsaetzliche Struktur wie die oeffentliche, enthaelt aber ausschliesslich sensible Werte. Fuer jede Umgebung, die in der oeffentlichen Datei existiert, kann hier eine passende Ergaenzung mit adminToken, apiKey oder dbPassword stehen, jeweils individuell fuer den eigenen Entwickler-Zugang.

PhpStorm fuehrt beim Senden eines Requests beide Dateien fuer die aktuell ausgewaehlte Umgebung automatisch zusammen. In der .http-Datei wird dabei nicht zwischen oeffentlich und privat unterschieden: Es wird schlicht {{adminToken}} referenziert, unabhaengig davon, aus welcher der beiden Dateien der konkrete Wert tatsaechlich stammt.

In der Praxis empfiehlt es sich, die private Datei zusaetzlich mit einem Kommentarfeld pro Eintrag zu versehen, etwa wann ein Token zuletzt erneuert wurde, da Admin-Token in Magento nach einer gewissen Zeit ablaufen und sonst unbemerkt zu Fehlern bei jedem Request fuehren.

{
  "local": {
    "adminToken": "eyJhbGciOiJIUzI1NiIs...",
    "apiKey": "local-dev-integration-key",
    "dbPassword": "magento_local_pw"
  },
  "staging": {
    "adminToken": "eyJhbGciOiJIUzI1NiIs...staging",
    "apiKey": "staging-integration-key"
  }
}

5. .gitignore korrekt konfigurieren, damit Secrets draussen bleiben

Der wichtigste Schritt, der in der Praxis am haeufigsten vergessen wird: http-client.private.env.json muss in der .gitignore des Projekts stehen, und zwar bevor die Datei zum ersten Mal angelegt wird. PhpStorm traegt die Datei nicht automatisch in die Ignore-Liste ein, das bleibt manuelle Aufgabe des Teams.

Wer die Datei versehentlich schon einmal committed hat, dem hilft ein einfaches Loeschen aus dem aktuellen Stand nicht, denn die Werte bleiben in der Git-Historie weiterhin sichtbar. In diesem Fall muessen betroffene Tokens zwingend rotiert und die Historie bereinigt werden, etwa mit git filter-repo oder dem BFG Repo-Cleaner.

# .gitignore im Projektroot
http-client.private.env.json
http-client.cookies

# Vorlage darf versioniert werden, sie enthaelt keine echten Werte
!http-client.private.env.json.example

6. Variablen in .http-Requests referenzieren

Innerhalb einer .http-Datei werden Variablen mit doppelten geschweiften Klammern eingesetzt, etwa {{baseUrl}}/rest/V1/products oder Authorization: Bearer {{adminToken}}. PhpStorm bietet dabei Autovervollstaendigung, sobald mindestens eine Umgebungsdatei im Projekt existiert und erkannt wurde.

Ueber das Umgebungs-Dropdown am oberen Rand des Editors waehlt jeder Entwickler die passende Umgebung aus, bevor ein Request gesendet wird. Diese Auswahl wird pro Projekt lokal gespeichert, sodass jeder Entwickler unabhaengig zwischen local und staging wechseln kann, ohne die Wahl der Kollegen zu beeinflussen.

Fuer Requests, die aufeinander aufbauen, etwa zuerst ein Produkt anlegen und danach dessen SKU fuer einen zweiten Aufruf wiederverwenden, unterstuetzt der HTTP Client zusaetzlich Response-Handler-Skripte, die einen Wert aus der Antwort automatisch in eine Client-Variable schreiben und damit manuelles Kopieren ueberfluessig machen.

### Produkt per SKU aus dem Katalog abrufen
GET {{baseUrl}}/rest/V1/products/{{sku}}
Authorization: Bearer {{adminToken}}
Accept: application/json

### GraphQL: Kategoriebaum abfragen
POST {{graphqlEndpoint}}
Content-Type: application/json
Store: {{storeCode}}

{
  "query": "{ categoryList(filters: { ids: { eq: \"2\" } }) { name url_path } }"
}

7. Team-Workflow: Was geteilt wird und was lokal bleibt

In einem funktionierenden Setup wird http-client.env.json wie jede andere Konfigurationsdatei im Repository gepflegt und im Code-Review mitbetrachtet, etwa wenn sich eine Staging-URL aendert. http-client.private.env.json bleibt dagegen fuer jeden Entwickler individuell und wird niemals per Chat, Wiki oder Repository geteilt.

Fuer neue Teammitglieder empfiehlt sich eine Vorlage namens http-client.private.env.json.example mit denselben Schluesseln, aber leeren oder Platzhalter-Werten. Diese Vorlage darf versioniert werden, da sie keine echten Secrets enthaelt, und beschleunigt das Onboarding erheblich, weil niemand raten muss, welche Variablen ueberhaupt benoetigt werden.

Bei groesseren Teams lohnt es sich zusaetzlich, die Pflege der oeffentlichen Umgebungsdatei einer festen Person oder dem jeweiligen Feature-Team zuzuordnen, damit Aenderungen an Basis-URLs oder Endpunkten nicht unkoordiniert von mehreren Seiten gleichzeitig vorgenommen werden und im schlimmsten Fall widerspruechliche Werte im Repository landen.

8. Sicherheitsaspekte ueber die reine Dateitrennung hinaus

Selbst mit korrekter Trennung bleiben Umgebungsdateien ein Risiko, wenn Tokens nie ablaufen oder nie rotiert werden. Fuer die lokale Entwicklung empfiehlt sich ein Integration-Token mit eingeschraenkten Rechten statt des vollen Admin-Tokens, gerade wenn mehrere Entwickler mit unterschiedlichen Zugriffsleveln parallel arbeiten.

Zusaetzlich lohnt sich ein Pre-Commit-Hook, der Dateinamen wie private.env.json blockiert, falls sie versehentlich doch gestaged werden. Tools wie gitleaks oder trufflehog lassen sich in die CI-Pipeline einhaengen und schlagen Alarm, bevor ein Secret ueberhaupt den Weg in den Hauptzweig des Repositories findet.

#!/usr/bin/env bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -q "private\.env\.json$"; then
  echo "Fehler: private Umgebungsdatei darf nicht committed werden."
  exit 1
fi

9. Vergleich zu anderen Ansaetzen fuer Umgebungsvariablen

Postman-Umgebungen loesen ein aehnliches Problem, sind aber an einen separaten Cloud-Account gebunden und leben ausserhalb des Projekt-Repositories, was den Bezug zum eigentlichen Code deutlich erschwert. .env-Dateien, wie sie aus Symfony- oder Laravel-Projekten bekannt sind, decken den PHP-Anwendungscode ab, aber nicht die HTTP-Testebene innerhalb der IDE.

Der eingebaute HTTP Client kombiniert beide Welten: Die Requests liegen als Textdateien im Repository und sind damit Teil der Code-Historie, waehrend private Werte sauber getrennt bleiben. Fuer Magento-Teams, die ohnehin viel mit REST- und GraphQL-Aufrufen arbeiten, ist das der pragmatischste Mittelweg zwischen Komfort und Sicherheit.

Wichtig bleibt dabei, dass die Entscheidung fuer den eingebauten HTTP Client keine Einbahnstrasse ist: Wer bereits eine umfangreiche Postman-Sammlung pflegt, kann einzelne Collections nach und nach in .http-Dateien uebersetzen, ohne den gesamten Bestand an einem Tag migrieren zu muessen.

10. Zusammenfassung

11. FAQ: HTTP Client Umgebungsdateien: Das Wichtigste auf einen Blick