Configure PhpStorm Professional to Use a Docker Compose PHP‑FPM Interpreter for Local Development

Useful answer

You can make PhpStorm Professional treat a PHP‑FPM container defined in docker-compose.yml as a remote CLI interpreter. This lets you run scripts, execute PHPUnit, and debug with Xdebug inside the container without installing PHP on your host. The setup consists of three parts: adding the Docker Compose interpreter, defining path mappings, and creating a Xdebug run configuration.

Mechanism: adding the interpreter

1. Start the service: docker-compose up -d php-fpm (run in the project root; you need Docker Desktop and your user must be in the docker group).
2. Open PhpStorm → Settings (or Preferences on macOS) → PHP → CLI Interpreter.
3. Click the + button, choose From Docker Compose.
4. In the dialog:
   • Server: select Docker (the default Docker daemon).
   • Compose file: browse to your docker-compose.yml.
   • Service: pick the PHP‑FPM service, e.g. php-fpm.
   • PHP binary path: usually /usr/local/bin/php inside the container (you can verify with docker-compose exec php-fpm which php).
   • Name: give it a readable label like Docker‑php-fpm.
5. Click OK. PhpStorm will probe the container; if the service is not running it will fail to detect the binary.
6. After the interpreter appears, switch to the Path Mappings tab. Map your host project directory to the container’s working directory, for example:
   • Host: /Users/dev/my‑project
   • Container: /var/www/html
7. Press Apply and OK.

Worked example: debugger configuration

Assuming Xdebug is installed in the container and listening on port 9003 (adjust if your container uses a different port or mode):

1. Go to Run → Edit Configurations….
2. Click the + button, choose PHP Remote Debug.
3. Set:
• Name: Docker Xdebug
• Filter debug connection by IDE key: optional, e.g. PHPSTORM
• Debug port: 9003
• External connections: check Can accept external connections.
4. In the Path Mappings area, ensure the same mappings you set for the interpreter are present (host path ↔ container path).
5. Click OK.
6. Start the listener: Run → Start Listening for PHP Debug Connections (toggle the phone icon in the top‑right toolbar).
7. Trigger a request that hits your application, e.g. curl http://localhost:8000/index.php if your compose exposes the web service on port 8000.
8. If a breakpoint is set in a local file under the mapped directory, PhpStorm should suspend execution and show the file in the editor.

Verification steps

• Open the PhpStorm terminal (View → Tool Windows → Terminal) and ensure it uses the Docker Compose interpreter (the status bar shows the interpreter name). Run php -v; the output should match the version inside the container.
• Set a breakpoint in public/index.php, start the Xdebug listener, and request the page via a browser or curl. Confirm the breakpoint is hit and the editor shows the local file.
• Create a PHPUnit run configuration that uses the Docker Compose interpreter, run a test, and check that the test output references container paths correctly mapped to your local files (e.g., /var/www/html/tests/ExampleTest.php:12 appears as /Users/dev/my-project/tests/ExampleTest.php:12 in the PhpStorm UI).

Limits and common mistakes

Requires PhpStorm Professional

The Docker Compose interpreter option is unavailable in the Community edition.

Service must be running when the interpreter is added

If php-fpm is not up, PhpStorm cannot locate the PHP binary and will report an error. Start the service first (docker-compose up -d php-fpm) or restart the interpreter detection after the container is healthy.

Path‑mapping mismatches

Breakpoints rely on exact correspondence between host and container paths. A common mistake is mapping /Users/dev/my-project to /var/www while the container actually mounts the code at /var/www/html. This causes ‘file not found’ in stack traces and breakpoints that never fire. Verify the container’s mount point with docker-compose exec php-fpm pwd and adjust the mapping accordingly.

Xdebug version and mode

Xdebug 3 uses the setting xdebug.mode=debug and defaults to port 9003. Older Xdebug 2 may use xdebug.remote_enable=1 and port 9000. Mismatched modes or ports result in the listener never receiving a connection. Check the container’s php.ini or the output of docker-compose exec php-fpm php -i | grep xdebug to confirm the active mode and port, then mirror those values in the PhpStorm remote debug configuration.

Performance impact of large bind mounts

If you mount the entire host filesystem or a very large directory, PhpStorm’s indexing and file watchers can slow down. Limit the bind mount to the project root only, and consider disabling unnecessary file watchers (Settings → Tools → File Watchers).

Windows path normalization

On Windows, PhpStorm may send paths like C:\\dev\\project while the container expects /c/dev/project or a Unix‑style path. Ensure the path mapping uses the same format on both sides; you can use docker-compose exec php-fpm pwd to see the container’s internal format and adjust the host side accordingly (e.g., map C:/dev/project to /var/www/html).

Practical way to check the result

After completing the setup, run a simple script that prints the interpreter’s environment:

# In PhpStorm terminal (using the Docker Compose interpreter)
echo "PHP version: " && php -v
echo "Include path: " && php -r "echo get_include_path();"

Compare the output with what you see when you exec directly into the container (docker-compose exec php-fpm php -v). Matching values confirm that PhpStorm is correctly talking to the container.