Using PhpStorm’s Docker Integration to Run and Debug PHP Inside Containers

Problem: Switching between host PHP and containerized PHP breaks debugging flow

When you move a PHP project into Docker, you lose the instant run‑and‑debug convenience that PhpStorm provides for local PHP interpreters. Manually starting containers, attaching debuggers, and syncing file changes adds friction and can lead to mismatched environments.

Thesis: PhpStorm’s built‑in Docker plugin lets you treat a container as just another PHP interpreter, preserving run configurations, live reload, and Xdebug debugging without leaving the IDE.

1. Enable the Docker plugin and connect a Docker daemon

Open Settings → Plugins, search for “Docker”, and ensure the plugin is installed and enabled. Then go to Tools → Docker and click the + button to add a Docker server. For a local daemon, accept the default Unix socket (/var/run/docker.sock) on Linux/macOS or the named pipe on Windows. If you use a remote daemon, provide the TLS certificate paths as prompted.

Verify the connection: the Docker tool window should show a green status and list any existing images.

2. Prepare a minimal Dockerfile for your PHP application

Place a Dockerfile at the project root. Below is a typical example for a PHP 8.2 app with Xdebug enabled:

# Dockerfile
FROM php:8.2-cli

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

# Install Xdebug (optional but useful for debugging)
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

# Set working directory
WORKDIR /var/www/html

# Copy composer files and install dependencies
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

# Copy application source
COPY . .

# Expose a port for the built‑in PHP server (if needed)
EXPOSE 8000

CMD ["php", "-S", "0.0.0.0:8000", "-t", "public"]

This file installs Xdebug and configures it to connect back to the host machine (the special host.docker.internal address works on Docker Desktop; on Linux you may need to adjust the IP).

3. Create a run configuration that launches the container

From the main menu choose Run → Edit Configurations…, click the + button, and select Docker → Image. Fill in:

• Image tag: my-php-app:latest (or leave blank to build from Dockerfile)
• Container name: my-php-app-container
• Bind ports: 8000:8000 (optional, for the PHP built‑in server)
• Bind mounts: Click + → Bind Mount, set Host path: $ProjectFileDir$, Container path: /var/www/html, and check Read‑only if you only need the IDE to see changes.
• Command: Leave empty to use the CMD from the Dockerfile, or override with php -S 0.0.0.0:8000 -t public.

Apply and close the dialog.

4. Run the container and verify live code reload

Click the Run button next to the configuration. PhpStorm builds the image (if needed), starts the container, and attaches the Docker tool window. You should see container output similar to:

PHP 8.2.12 Development Server started at http://0.0.0.0:8000

Open a browser to http://localhost:8000 (or the appropriate host/port) and confirm the application loads. Edit a PHP file in PhpStorm; because the project directory is mounted as a volume, the change appears instantly inside the container without rebuilding.

5. Debug with Xdebug inside the container

Set a breakpoint in your PHP code. In the run configuration, ensure the Debug option is selected (the bug icon). Click Debug instead of Run. PhpStorm will:

1. Start the container with the same volume mounts.
2. Wait for Xdebug to connect back to the IDE (the xdebug.client_host setting points to the host).
3. Hit the breakpoint and show the usual debugger UI (variables, stack trace, watches).

If the breakpoint is not hit, open the Docker tool window, select the container, and check the Logs tab for Xdebug connection messages. Common issues:

• Wrong xdebug.client_host – on Linux use the host’s IP address (e.g., 172.17.0.1).
• Firewall blocking port 9003 (default Xdebug debug port). Ensure the IDE’s debug port is open.

Limitation: Volume performance on Windows

When the project directory is large, mounting it as a bind volume on Windows can cause noticeable I/O latency because of the default file‑sharing mechanism (CIFS). Symptoms include slow page reloads and delayed breakpoint hits.

Practical check: open a terminal inside the container (docker exec -it my-php-app-container bash) and run a simple timing command, e.g., time find /var/www/html -type f -name '*.php' | wc -l. Compare the result to the same command run on the host. If the container time is significantly higher, consider:

• Using Docker’s --cached or --delegated mount flags (available via PhpStorm’s bind‑mount options).
• Switching to a Windows‑based Docker Engine with the WSL 2 backend and enabling the \wsl$ file sharing for better performance.
• Copying only the necessary source into the image at build time and using a separate volume for configuration files only.

Closing: Keep your development flow inside PhpStorm

By leveraging PhpStorm’s Docker integration you gain:

• One‑click container start/stop from the IDE.
• Automatic volume mapping for live code edits.
• Full Xdebug debugging without manual docker exec or port forwarding.
• Visibility of images, containers, and logs in a dedicated tool window.

Start with a small service, verify the connection and debugging workflow, then expand to multi‑container setups using Docker Compose (the same Docker tool window supports docker-compose up and down). This approach reduces context switching and keeps your environment reproducible across teammates.