PhpStorm HTTP Client Environment Files: Managing Private Variables Securely

1. Why environment files are necessary for API testing at all

Every Magento project has at least three environments: a local Docker instance, a staging system, and production. Each has its own base URL, its own admin credentials, and its own integration tokens. Anyone who hardcodes these values into a .http file has to touch the request text on every environment switch and risks the file carrying the wrong, or even secret, values into the next commit.

PhpStorm solves this by feeding variables into requests from separate JSON files. The request itself stays environment agnostic, only the currently active environment decides which concrete values are actually used. For a Magento team this means the same .http file works against local, staging, and production without a single line of the request ever changing.

In practice this shows up especially in Magento projects with multiple stores and websites, where store specific headers such as Store or Content-Currency also need to be set correctly. Without environment files, such details quickly end up scattered across comments or stuck in a single developer's memory instead of being maintained centrally.

2. The difference between the public and the private environment file

http-client.env.json is meant for values that can be shared with the whole team: base URLs, store codes, public endpoint paths, or the timezone in use. This file lives in the project directory and is checked into Git like any other config file, because it contains nothing an attacker could exploit.

http-client.private.env.json, on the other hand, is meant for anything personal or secret: admin bearer tokens, personal integration keys, database passwords used for local testing. PhpStorm expects this file in the project root as well and merges its values with the public file. It is important that both files use the same key for the same environment name, otherwise the values will not merge correctly.

3. http-client.env.json: structure of the public file

The public file defines a separate JSON object per environment. Common choices are at least local, staging, and production, each with its own baseUrl and the store specific values needed for Magento REST or GraphQL calls, such as storeCode or graphqlEndpoint.

Because this file is versioned, it should only ever contain values that could equally sit in public documentation. A simple test helps decide: would it matter if this file were accidentally exposed publicly on the internet? If the answer is no, the value belongs here, not in the private variant.

{
  "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: structure of the private file

The private file shares the basic structure of the public one but contains only sensitive values. For every environment that already exists in the public file, this one can hold a matching adminToken, apiKey, or dbPassword, individual to each developer's own access.

When a request is sent, PhpStorm automatically merges both files for the currently selected environment. Inside the .http file there is no distinction between public and private, it simply references {{adminToken}}, regardless of which of the two files actually supplied the value.

In practice it helps to add a comment field per entry in the private file noting when a token was last renewed, since admin tokens in Magento expire after a certain time and otherwise cause requests to fail unnoticed.

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

5. Configuring .gitignore correctly so secrets stay out

The single most important step, and the one most often forgotten in practice: http-client.private.env.json must be added to the project's .gitignore before the file is created for the first time. PhpStorm does not add the file to the ignore list automatically, that remains a manual team task.

Anyone who has already committed the file accidentally cannot fix it by simply deleting it from the current state, since the values remain visible in the Git history. In that case, affected tokens must be rotated immediately and the history rewritten, for example with git filter-repo or BFG Repo-Cleaner.

# .gitignore in the project root
http-client.private.env.json
http-client.cookies

# The template may be versioned, it holds no real values
!http-client.private.env.json.example

6. Referencing variables inside .http requests

Inside a .http file, variables are inserted with double curly braces, for example {{baseUrl}}/rest/V1/products or Authorization: Bearer {{adminToken}}. PhpStorm offers autocompletion for this as soon as at least one environment file exists and has been recognized.

Every developer picks the matching environment from the dropdown at the top of the editor before sending a request. This selection is stored locally per project, so each developer can switch between local and staging independently without affecting a colleague's choice.

For requests that build on each other, for example creating a product first and then reusing its SKU for a second call, the HTTP client additionally supports response handler scripts that automatically write a value from the response into a client variable, making manual copying unnecessary.

### Fetch a product from the catalog by SKU
GET {{baseUrl}}/rest/V1/products/{{sku}}
Authorization: Bearer {{adminToken}}
Accept: application/json

### GraphQL: query the category tree
POST {{graphqlEndpoint}}
Content-Type: application/json
Store: {{storeCode}}

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

7. Team workflow: what gets shared and what stays local

In a working setup, http-client.env.json is maintained in the repository like any other config file and reviewed alongside code changes, for instance when a staging URL changes. http-client.private.env.json, by contrast, stays individual to each developer and is never shared via chat, wiki, or repository.

For new team members, a template called http-client.private.env.json.example with the same keys but empty or placeholder values is worth adding. This template can be versioned since it holds no real secrets, and it speeds up onboarding considerably because nobody has to guess which variables are even needed.

In larger teams it also helps to assign maintenance of the public environment file to a fixed person or the relevant feature team, so changes to base URLs or endpoints are not made uncoordinated from multiple sides at once, which in the worst case leaves conflicting values in the repository.

8. Security considerations beyond plain file separation

Even with correct separation, environment files remain a risk if tokens never expire or are never rotated. For local development, an integration token with restricted rights is recommended over the full admin token, especially when several developers with different access levels work in parallel.

It also pays off to add a pre-commit hook that blocks filenames like private.env.json in case they get staged by accident. Tools such as gitleaks or trufflehog can be wired into the CI pipeline and raise an alarm before a secret ever reaches the main branch of the repository.

#!/usr/bin/env bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -q "private\.env\.json$"; then
  echo "Error: private environment file must not be committed."
  exit 1
fi

9. Comparison with other approaches to environment variables

Postman environments solve a similar problem but are tied to a separate cloud account and live outside the project repository, which makes the connection to the actual code much harder to maintain. .env files, familiar from Symfony or Laravel projects, cover the PHP application code but not the HTTP testing layer inside the IDE.

The built-in HTTP client combines both worlds: requests live as plain text files inside the repository and are therefore part of the code history, while private values stay cleanly separated. For Magento teams that already work heavily with REST and GraphQL calls, this is the most pragmatic middle ground between convenience and security.

It is worth noting that choosing the built-in HTTP client is not a one way street: anyone already maintaining an extensive Postman collection can translate individual collections into .http files gradually, without having to migrate the entire set in a single day.

10. Summary

11. FAQ: HTTP Client Environment Files: The Essentials at a Glance