PhpStorm as the Hub for Docker and Magento Projects

1. What Really Makes PhpStorm a Hub

PhpStorm is not a collection of individual features, but an integrated system. The key is understanding which parts of this system actually work together on Docker and Magento projects, and how they reinforce each other. A remote PHP interpreter pointing at the Docker container is the foundation for everything else: autocompletion with the correct PHP context, PHPUnit execution inside the container, Xdebug sessions that actually work, and external tools that use the right PHP version.

For Magento projects using the Mark Shust Docker setup, there's an additional wrinkle: development happens exclusively through container commands. The local PHP installation plays no role at all. PhpStorm needs to reflect that reality so autocompletion, navigation, and debugging all operate with the same PHP context that's visible in the browser. Once the remote interpreter is set up correctly, a lot of things fall into place on their own: PhpStorm recognizes the PHP context, Xdebug configuration automatically shows the right options, and run configurations use the container's PHP.

The limits of PhpStorm show up where Docker orchestration gets more complex. Starting Docker Compose with many services, watching logs from multiple containers at once, controlling build processes: all of that stays more efficient in the terminal. PhpStorm complements the terminal workflow, it doesn't fully replace it.

2. Setting Up the Remote PHP Interpreter for Docker

The remote PHP interpreter is the single most important setting for Docker-based PHP projects in PhpStorm. It connects PhpStorm to the PHP inside the container and lets every IDE feature operate with the correct PHP context. You configure it under Settings → PHP, where you can create a new profile under "CLI Interpreter".

For the Mark Shust setup, choose "Docker Compose" as the interpreter type and select the corresponding compose.yaml. PhpStorm then starts the PHP container for analysis and tool invocations. Alternatively, you can use an SSH tunnel to the container or connect the interpreter directly via the Docker socket. Important: the PHP version in the remote interpreter must match the one in the container. With PHP 8.4 and strict types, this matters even more, because otherwise PhpStorm will flag incorrect type errors.

# compose.yaml (Mark Shust setup) - relevant phpfpm service
services:
  phpfpm:
    image: markoshust/magento-php:8.4-fpm-0
    volumes:
      # Local src/ is mounted at /var/www/html inside the container
      - ./src:/var/www/html:cached
      - ~/.composer:/var/www/.composer:cached
      - ~/.ssh/id_rsa:/var/www/.ssh/id_rsa:cached
    environment:
      XDEBUG_MODE: "${XDEBUG_MODE:-off}"
      XDEBUG_CLIENT_HOST: "${XDEBUG_CLIENT_HOST:-host.docker.internal}"
      XDEBUG_CLIENT_PORT: "9003"
    extra_hosts:
      - "host.docker.internal:host-gateway"

# PhpStorm remote interpreter configuration:
# Server: Docker Compose
# Configuration files: ./compose.yaml
# Service: phpfpm
# Path mappings: ./src -> /var/www/html

Once the remote interpreter is set up, PhpStorm shows an icon next to the PHP version that indicates the connection status. Clicking "Refresh" synchronizes the installed PHP extensions and activated modules. That way PhpStorm knows which functions and classes are available inside the container, including Magento-specific autoloader information.

3. Connecting Xdebug in the Docker Container with PhpStorm

Xdebug in the container is often the first stumbling block in Docker-based PhpStorm setups. The basic principle: Xdebug inside the container actively connects to PhpStorm on the host (not the other way around). PhpStorm listens on port 9003, Xdebug knows the host address via host.docker.internal, and it establishes the connection as soon as a debug session starts.

With the Mark Shust setup, Xdebug is already preconfigured. The bin/xdebug enable script sets the environment variable XDEBUG_MODE=debug and restarts the PHP container. In PhpStorm, all you need to do is enable Run → Start Listening for PHP Debug Connections. Breakpoints in PhpStorm are then hit on the next HTTP request. Important: the path mappings need to be correct so PhpStorm can map the container paths back to local files.

# Xdebug configuration inside the container (set automatically by the Mark Shust setup)
# /usr/local/etc/php/conf.d/xdebug.ini

[xdebug]
zend_extension=xdebug

; debug = breakpoints, remote_autostart
; coverage = code coverage for PHPUnit
; profile = profiling (never leave this active in dev)
xdebug.mode=debug

; The container actively connects to the host
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

; Session ID for browser triggers (XDEBUG_SESSION cookie)
xdebug.idekey=PHPSTORM

; Start a debug session without a browser trigger (for CLI debugging)
; xdebug.start_with_request=yes  <- only enable for bin/debug-cli

; Log for connection issues
xdebug.log=/tmp/xdebug.log
xdebug.log_level=3

For CLI debugging, for example debugging Magento migrations or console commands, use bin/debug-cli enable, which sets XDEBUG_SESSION=PHPSTORM as an environment variable. That way Xdebug automatically starts a debug session on every CLI PHP call, without needing a browser cookie. "Listen" needs to be active in PhpStorm here as well.

4. Running Magento CLI Commands from PhpStorm

Running Magento CLI commands from PhpStorm saves context switches. Using run configurations of type "Shell Script", you can wire up any wrapper script from the bin/ directory. Useful configurations: bin/magento cache:flush on a shortcut, bin/magento setup:upgrade as a dedicated run task, or a combined task that runs CSS build, static deploy, and cache flush in sequence.

A compound run configuration lets you bundle several of these tasks into one configuration and start them all with a single click. That's especially useful for the deploy workflow: build CSS, delete static files, deploy static content, flush the cache, all in one step straight from PhpStorm.

#!/usr/bin/env bash
# Example: compound deploy script as a run configuration
# Script path: bin/deploy-dev
# PhpStorm: Run -> Edit Configurations -> + -> Shell Script

set -euo pipefail

# 1. Rebuild CSS (Tailwind v4)
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build

# 2. Delete static files, always do this first!
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/*
cd ..

# 3. Deploy static content
bin/magento setup:static-content:deploy de_DE \
    -t Mironsoft/default \
    --jobs=4 \
    -f

# 4. Flush cache
bin/magento cache:flush

echo "Deploy finished."

For frequently used individual Magento commands, it's worth setting them up under Settings → Tools → External Tools instead of as a run configuration. External tools can be shown directly in the context menu and are immediately available without opening the run configuration selector.

5. Path Mappings: Mapping Container Paths to Local Paths

Path mappings are the bridge between the local file system and the container. PhpStorm needs to know that /var/www/html/app/code/Vendor/Module/Model/Foo.php inside the container is identical to /home/mir/development/mironsoft/src/app/code/Vendor/Module/Model/Foo.php locally. Without this mapping, Xdebug doesn't work: breakpoints aren't recognized because PhpStorm can't resolve the file paths coming from Xdebug messages.

Path mappings are configured in several places in PhpStorm: in the remote interpreter (for autocompletion context), in the Xdebug server under Settings → PHP → Servers (for breakpoints), and in the run configurations for PHPUnit (for test execution). All three places need to be configured consistently. In the Mark Shust setup, the basic rule is simple: local ./src corresponds to container path /var/www/html.

6. Controlling Docker Compose Services from PhpStorm

PhpStorm automatically detects compose.yaml files and offers a Services tab in the tool window that shows the status of all services. From there you can start, stop, and restart individual services without opening the terminal. For the day-to-day Magento workflow, that's enough for simple operations like restarting Nginx or phpfpm after a configuration change.

The real value, though, is in the Services window for logs: every container service has its own log stream shown directly inside PhpStorm. That way you can keep an eye on the phpfpm log and the Nginx log at the same time during development, without opening two terminal tabs. When you hit a Magento error like "502 Bad Gateway", the phpfpm log immediately shows what's actually causing it.

7. Following Container Logs Directly in PhpStorm

Both container logs and Magento's own logs can be shown directly inside PhpStorm. For container logs, use the Services window. For Magento logs (var/log/exception.log, var/log/system.log), run configurations of type "Shell Script" with the command bin/log exception.log work well. Alternatively there's a log viewer configuration under Run Configuration → Logs that watches specific files in the project and updates automatically when they change.

Particularly useful: in the Run window, you can have a Magento command running and the log viewer active at the same time. That way, when running bin/magento setup:upgrade, you immediately see if errors show up in exception.log, without manually switching between the terminal and the log.

8. What's Better Left in the Terminal

PhpStorm is not a full replacement for the terminal. Certain workflows are faster and more efficient in the terminal. That includes: complex Docker Compose operations with multiple flags, the initial setup of a Magento environment (bin/setup), Composer operations (bin/composer install, bin/composer update), SSH connections into the container (bin/bash) for interactive debugging sessions, and build processes that produce a lot of output and where you need the full scroll history.

The integrated terminal in PhpStorm (View → Tool Windows → Terminal) offers a good middle ground: you stay inside PhpStorm, but still have a full terminal with the project's working directory. For most day-to-day Magento operations, that's enough, without switching to an extra window.

9. Comparison: PhpStorm Integration vs. Terminal Workflow

The decision about what to do in PhpStorm and what to do in the terminal depends on the frequency and complexity of the operation. The table below shows the typical split for a Magento development workflow.

The most productive workflow combines both approaches: PhpStorm as the hub for autocompletion, debugging, and frequent commands, and the integrated terminal for everything else. Anyone trying to force everything into PhpStorm ends up fighting the IDE, and anyone who ignores the terminal entirely loses speed on complex operations.

10. Summary

PhpStorm becomes a genuine hub for Docker and Magento projects once the remote PHP interpreter is configured correctly. Everything else, Xdebug integration, PHPUnit inside the container, external tool calls with the right PHP, builds on top of that. Xdebug in the container works reliably with the Mark Shust setup once path mappings and the listener in PhpStorm are configured correctly. Magento CLI commands as run configurations and external tools save context switches in day-to-day work.

The most important takeaway: PhpStorm doesn't replace the terminal, it complements it. Debugging, autocompletion, code navigation, and frequent commands benefit from IDE integration. Complex Docker operations, Composer, and interactive shell sessions stay more efficient in the terminal. Knowing where that boundary sits lets you use both tools well.

11. FAQ: PhpStorm as the Hub for Docker and Magento