Using PhpStorm’s Docker Integration to Run and Debug PHP Apps

The problem: environment drift on a developer workstation

When you switch between branches or collaborate with teammates, small differences in PHP versions, extensions, or configuration can cause tests to pass locally but fail in CI. Manually keeping a local LAMP stack in sync is tedious and error‑prone.

Why PhpStorm’s built‑in Docker support helps

PhpStorm can treat a Dockerfile or docker‑compose.yml as a first‑class run target. When you launch a Docker run configuration, the IDE:

• Mounts the project directory into the container as a volume, so edits appear instantly without rebuilding the image.
• Automatically configures Xdebug inside the container and sets up path mappings, allowing breakpoints to hit as if the code were running locally.
• Provides the Services tool window to view containers, logs, exec into a shell, and manage Compose stacks without leaving the IDE.

Worked example: a simple PHP project with Docker

Assume a project with index.php and a Dockerfile that installs PHP 8.2 and Xdebug.

# Dockerfile
FROM php:8.2-cli
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
WORKDIR /app
COPY . /app
CMD ["php", "-S", "0.0.0.0:8000", "-t", "/app"]

To create the run configuration:

1. Open Run → Edit Configurations….
2. Click the + button, choose Docker.
3. Set Type to Dockerfile, point to the Dockerfile above, and give the configuration a name (e.g., php‑docker).
4. In the Bindings tab, ensure the Project directory is mapped to /app (the default when the Dockerfile is in the project root).
5. Apply and close.

Start the configuration with Run → Debug 'php‑docker'. The Services tool window will show a running container, its logs, and a shell button.

Debugging inside the container

Set a breakpoint in index.php. Because PhpStorm injected Xdebug and configured path mappings (/app ↔ project root), hitting the URL http://localhost:8000 will suspend execution at the breakpoint. The Variables view will display super‑globals, request data, and any local variables exactly as you would see with a local PHP interpreter.

Trade‑offs and practical verification

While the integration smooths out environment differences, there are a few considerations:

• Docker daemon availability – you must have a running Docker Engine and the user must be able to connect (e.g., member of the docker group on Linux, or Docker Desktop running on macOS/Windows).
• File‑system mount performance – on Windows using the default Hyper‑V driver can introduce latency for large projects; switching to wsl2 or using a cached volume may improve speed.
• Advanced Docker features – options like custom networks, build arguments, or privileged containers are not exposed in the UI; you need to edit the run configuration’s Command line options or use a docker‑compose.override.yml file.

To verify that the setup works:

1. Open Settings → Build, Execution, Deployment → Docker and click Test connection. A success message indicates the IDE can talk to the daemon.
2. Run the Docker configuration; the Services window should list a container with the image name you built and show stdout/stderr.
3. Trigger a request to the application, confirm the debugger stops at your breakpoint, and inspect variables.

Actionable next step

If you are starting a new PHP feature branch or onboarding a teammate, add a Dockerfile that mirrors your production PHP version, create the Docker run configuration as described, and use the Services window to manage the container. This gives you a reproducible environment without leaving PhpStorm, and you can switch back to a local interpreter at any time if you need to test host‑specific behavior.