Run and Debug a PHP Application in Docker Using PhpStorm

Desired outcome

Run a PHP application inside a Docker container from PhpStorm, expose it on a host port, and debug it with Xdebug breakpoints.

Prerequisites

• Docker Engine installed and running.
• PhpStorm 2023.2 or later with the Docker plugin enabled.
• A PHP project that contains a Dockerfile defining a web server (e.g., nginx + php‑fpm) and exposes the application port.
• The PhpStorm user has permission to access the Docker daemon (on Linux add the user to the docker group or configure sudo).

Procedure

1. Open Settings → Build, Execution, Deployment → Docker.
2. Click the + button, choose Docker, keep the default Unix socket (/var/run/docker.sock) or specify a TCP address, click Apply.
3. Navigate to Run → Edit Configurations, press + and select Docker Run.
4. In the configuration form:
• Set Container name to a meaningful value, e.g., my-php-app.
• Select the Dockerfile from your project.
• Under Port bindings, map container port 80 to a host port, for example 8080 (field Host Port).
• Under Volume bindings, add a bind mount: Host path = absolute path to your project source, Container path = /var/www/html. Use a .dockerignore file to exclude vendor and node_modules if they exist.
5. Click OK to save the configuration.

Expected checks

1. Start the configuration via the Run dropdown or the Services tool window.
2. In the Services window, locate the container; it should show a green icon and list the port mapping (0.0.0.0:8080->80/tcp).
3. Open a browser at http://localhost:8080 (replace 8080 with your host port) and verify the PHP application’s index page loads.
4. Enable Xdebug listening: Settings → PHP → Debug, ensure Can accept external connections is on.
5. Set a breakpoint in a PHP file, click the Debug button next to the configuration, make a request (e.g., refresh the browser), and confirm the debugger session appears in the Debug tool window and suspends at the breakpoint.

Recovery options

1. If the container fails to start, open the Docker log tab inside the run configuration to view error messages.
2. Correct Dockerfile syntax, resolve port conflicts (change host port), or adjust volume paths, then rerun.
3. To revert, stop the container via the Services window (right‑click → Stop).
4. Optionally delete the run configuration from Run → Edit Configurations.
5. Run docker system prune -f in a terminal to remove stopped containers and free space (only if you are sure no needed containers remain).