Streamlining PHP Development with PHPStorm’s Built‑In Docker Integration

Problem: Context‑Switching Between IDE and Terminal

When a PHP project runs inside a Docker container, developers often have to:

• Open a terminal, docker build, docker run, and docker exec to debug.
• Switch between the IDE and the command line to view logs or hit breakpoints.
• Maintain separate Dockerfiles for each environment.

These steps increase cognitive load, introduce human error, and slow the feedback loop. The question is: can the IDE itself handle Docker?

Thesis: PHPStorm’s Docker Integration Turns the IDE Into a Full‑Featured Container Manager

PHPStorm ships with a Docker plugin that lets you:

• Discover local and remote Docker daemons.
• Build images, start containers, and manage volumes from the IDE.
• Configure Run/Debug configurations that automatically attach Xdebug inside the container.
• Parse Docker Compose files for multi‑service development.

By treating Docker as a first‑class resource, PHPStorm removes the need for manual CLI work and keeps the developer in a single context.

Step 1: Enable Docker in PHPStorm

1. Open Settings / Preferences (Ctrl+Alt+S on Windows/Linux, ⌘+, on macOS).
2. Navigate to Build, Execution, Deployment > Docker.
3. Click the + button and select Docker for Windows (or Docker for Mac / Docker Machine).
4. For a remote daemon, choose Docker Engine and provide the host URL (e.g., tcp://:2375) and credentials if required.
5. Click Test Connection. A green check means PHPStorm can communicate with the daemon.
6. Click OK to save.

Once enabled, the Docker tool window will list available images and containers.

Step 2: Build an Image from a Dockerfile

Assume you have a simple PHP application in app/ with index.php. Create a Dockerfile:

# Dockerfile
FROM php:8.3-apache
COPY app/ /var/www/html/
RUN docker-php-ext-install mysqli pdo_mysql
EXPOSE 80

In PHPStorm:

1. Open the Docker tool window.
2. Right‑click Images and choose Build Image….
3. Point to the Dockerfile, give the image a name (e.g., myapp:local), and start the build.
4. Once the build succeeds, the image appears in the list.

Step 3: Run the Container and Attach Xdebug

To debug, you need a Run/Debug configuration that:

• Starts the container.
• Maps port 9003 (Xdebug 3) to the host.
• Sets environment variables for Xdebug.

In Run | Edit Configurations…, click + and choose Docker Compose (or Docker if you’re using a single container).

Example configuration for a single container:

{
  "name": "Run MyApp in Docker",
  "type": "docker",
  "image": "myapp:local",
  "ports": [
    {
      "containerPort": 80,
      "hostPort": 8080
    },
    {
      "containerPort": 9003,
      "hostPort": 9003
    }
  ],
  "env": {
    "XDEBUG_MODE": "debug,develop",
    "XDEBUG_START_WITH_REQUEST": "yes",
    "XDEBUG_CLIENT_HOST": "host.docker.internal"
  }
}

Save and run the configuration. PHPStorm will launch the container and automatically start an Xdebug listener on port 9003. Place a breakpoint in index.php and hit it when you navigate to http://localhost:8080.

Step 4: Use Docker Compose for Multi‑Service Environments

When your application depends on services like MySQL or Redis, create docker-compose.yml:

version: '3.9'
services:
  php:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:80"
      - "9003:9003"
    environment:
      XDEBUG_MODE: debug,develop
      XDEBUG_START_WITH_REQUEST: yes
      XDEBUG_CLIENT_HOST: host.docker.internal
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: appdb
    ports:
      - "3306:3306"

In PHPStorm, add a Docker Compose configuration, point to the file, and select the php service. PHPStorm will start both services, expose the ports, and attach Xdebug to the PHP container automatically.

Trade‑Offs and Limitations

• Docker Daemon Availability: The IDE cannot operate without a running Docker daemon. Ensure Docker Desktop (or a remote Docker host) is up and the API is reachable.
• Version Compatibility: Older PHPStorm releases may not understand newer Compose file formats (e.g., version: '3.9'). Verify that your IDE supports the Compose version you use.
• Resource Overhead: Running containers inside the IDE can consume CPU and memory, especially for large images or multi‑service stacks.
• Debug Configuration Complexity: Setting environment variables for Xdebug requires attention to detail; a mis‑typed variable can prevent breakpoints from firing.

Verification Checklist

1. Open Settings / Preferences > Docker and confirm the daemon is listed.
2. In the Docker tool window, build myapp:local and ensure it appears under Images.
3. Run the Run MyApp in Docker configuration and check that the container starts (visible in Containers list).
4. Open index.php, set a breakpoint, and navigate to http://localhost:8080. The breakpoint should hit.
5. For Compose, verify that both php and db services appear and that MySQL is reachable from the PHP container (e.g., via mysqli_connect()).

Actionable Closing

With PHPStorm’s Docker integration, you can:

• Eliminate manual CLI steps for building and running containers.
• Keep your debugging workflow inside the IDE, reducing context switching.
• Mirror production environments locally with Docker Compose.

Next steps: experiment with docker-compose.override.yml for environment‑specific overrides, and explore PHPStorm’s Docker Remote feature to manage containers on a CI server or a remote host.