Version-Control Your PHP API Checks with PhpStorm .http Files

The problem: API checks that live outside the code

Many PHP teams test endpoints with ad-hoc curl commands or Postman collections that never enter the repository. Those requests drift from the code, are not reviewed in pull requests, and disappear when a developer leaves. The result is API documentation that exists only in someone’s request history.

PhpStorm includes a built-in HTTP client that stores requests as plain-text .http files. Because they sit next to your PHP classes, they can be versioned, diffed, and reviewed like any other source file.

What a .http file looks like

A .http file uses a simple text syntax. The method and URL go on the first line, optional headers and body follow, and ### separates multiple requests in one file. Variables are declared with @name = value and referenced as {{name}}. PhpStorm displays a run gutter icon beside each request, and the response opens in the Services tool window.

Worked example: log in, then call a protected endpoint

Save the following as api/http/auth.http in your project. It authenticates against a local PHP API, saves the returned JWT, and uses it on the next request.

### Login
POST {{baseUrl}}/api/login
Content-Type: application/json

{
  "email": "[contact removed]",
  "password": "{{password}}"
}

> {%
// Response handler: extract the JWT for the next request
if (response.status === 200) {
  client.global.setVariable("token", response.body.json().access_token);
}
%>

### Orders
GET {{baseUrl}}/api/orders
Authorization: Bearer {{token}}

> {%
// Response handler: assert status and body shape
if (response.status !== 200) {
  throw new Error("Expected 200, got " + response.status);
}
const body = response.body.json();
if (!Array.isArray(body)) {
  throw new Error("Expected an orders array");
}
%>

Open the file in PhpStorm and click the gutter icon next to ### Login. The response appears in the Services tool window. If the login handler succeeds, the token variable is available to the Orders request. Run Orders and confirm it sends Authorization: Bearer {{token}} with the substituted value.

Environments, variables, and secrets

PhpStorm can swap variable values through environment files so the same .http file targets local, staging, or CI. A common setup uses a shared file and a private file for secrets:

• http-client.env.json — committed to the repository
• http-client.private.env.json — local only, add to .gitignore

Example shared environment file:

{
  "development": {
    "baseUrl": "http://localhost:8000",
    "password": "dev-password"
  },
  "staging": {
    "baseUrl": "https://staging.example.com",
    "password": "{{staging_password}}"
  }
}

Environment filenames and script directives vary by PhpStorm release. Open your IDE settings and confirm the HTTP client section before standardizing on these names. Never commit real tokens or passwords; reference them from the private environment file instead.

Trade-offs: what this is not

• There is no built-in collection runner or cloud sync equivalent to Postman.
• Response scripts are a limited JavaScript subset, not a full test framework.
• Complex OAuth2 device flows and chained auth can be awkward to script.
• Running .http files in CI usually requires separate tooling; do not assume PhpStorm executes them in your pipeline.

Use .http files for exploratory checks and living documentation while you code. Keep meaningful assertions and regression coverage in PHPUnit or Pest.

How to verify it works on your machine

1. Create api/http/auth.http with the example above.
2. Open it in PhpStorm and confirm a run gutter icon appears beside each request.
3. Select an environment from the editor dropdown.
4. Run Login, then run Orders and confirm the token variable carries over.
5. Switch environments and confirm only baseUrl and password change.

If the gutter icon or environment dropdown is missing, check your PhpStorm version’s HTTP client documentation before rolling the pattern out to the team.

Closing

Treat .http files as versioned API scratchwork. Commit them, review them in pull requests, and keep them as lightweight smoke checks while endpoints are active. If you decide to stop using them, delete the files and remove any private environment reference from .gitignore. Running a request against a local API does not change IDE state, though the request itself may mutate data on the target server, so avoid running destructive endpoints repeatedly.