Zero-Config Docker Compose Detection in PhpStorm in Detail

1. Zero-Config as a Promise and as Reality

The term zero-config raises the expectation that a project can simply be opened and everything works immediately, without a single manual setting. For PhpStorm and Docker Compose this largely holds true for simple setups: a single docker-compose.yml with one PHP service and one database is detected when the project opens, and PhpStorm directly offers to generate a run configuration from it. For many smaller projects that is entirely sufficient.

As soon as a setup combines several compose files, for example a base file and multiple override files for different environments, as is common in the Mark Shust Docker setup for Magento, the zero-config experience turns into a starting point that needs adjustment. That is not a flaw in PhpStorm but a logical consequence of the fact that compose overrides are combined at runtime, and PhpStorm cannot always unambiguously predict that combination.

2. Prerequisites: Enabling Docker Integration in PhpStorm

Docker support ships as a bundled plugin in most PhpStorm editions but should be checked and, if necessary, enabled under Settings, Plugins. In addition, a connection to the local Docker engine must be set up under Settings, Build, Execution, Deployment, Docker, either via the local Docker socket on Linux and macOS or via the corresponding named pipe configuration on Windows.

Once the connection is set up correctly, the Docker tool window appears at the bottom of the IDE, showing running containers, images and compose stacks. This tool window is the central place to verify that PhpStorm has contact with the Docker engine at all, before any automatic compose file detection can work meaningfully.

Settings > Build, Execution, Deployment > Docker
  + (add Docker connection)
  Linux/macOS: Unix socket, default path usually auto-detected
  Test: "Connection successful" must appear

3. How Automatic Detection Works in Detail

When PhpStorm opens a project directory, it scans the project root and defined subfolders for files named docker-compose.yml or compose.yaml. If such a file is found, the IDE offers, via a small icon at the file margin, to create a run configuration of type Docker-Compose directly from it. This configuration automatically references the found file and lists every service defined inside it for selection.

For each service, PhpStorm additionally reads the exposed ports, mounted volumes and environment variables from the compose file and displays them in the generated run configuration. For a single PHP service with a clearly defined build context, this works reliably and almost entirely saves the manual creation of a configuration.

4. Practical Example: Automatic Detection With One Service

A minimal docker-compose.yml with a service named phpfpm that references a local Dockerfile and exposes port 9000 is typically interpreted correctly by PhpStorm without any manual input. The generated run configuration allows directly starting and stopping the container from the IDE, without opening a terminal, and the service immediately appears in the Docker tool window with a status indicator.

Log output mapping also works reliably in this simple case: clicking the running container in the tool window opens the log stream directly inside the IDE, with search and filter functionality. For quick debugging sessions on simple setups, this almost entirely replaces switching to the terminal and noticeably speeds up the feedback cycle.

5. Limits With Multi-File Compose Setups

As soon as a project combines multiple compose files, for example a docker-compose.yml as a base and a docker-compose.dev.yml as an override for development environments, as is common in the Mark Shust setup, PhpStorm often only automatically detects the file found first. The override file is usually also recognized as a standalone compose file, but PhpStorm does not automatically combine both into a single run configuration the way the docker compose command would with the -f flag for multiple files.

In practice this means an automatically generated run configuration may reference only the base file, leaving out environment variables or volume mounts that actually come from the override file. If this difference goes unnoticed, the container still starts but behaves differently than with a manual docker compose up using both files, which can lead to hard to trace debugging problems.

6. Environment Variables and .env Files in Detection

PhpStorm automatically reads an .env file in the same directory as the docker-compose.yml and resolves variables referenced within the compose file, for example for image tags or port numbers. This resolution is usually reliable as long as the .env file sits in the default directory. If it sits at a different path or is explicitly referenced via the --env-file option, the automatic configuration frequently fails to detect it.

For Magento setups with multiple environment tiers, for example separate .env files for local development and CI, this means the run configuration must be manually extended with the correct .env file path after automatic generation. Otherwise PhpStorm silently falls back to default values, which particularly with database credentials leads to connection errors that are not obviously linked to the compose configuration at first glance.

7. Manually Adjusting the Generated Configuration

The generated run configuration can be fully customized under Run, Edit Configurations. The most important step for multi-file setups is adding additional files under the Compose Files field, in the correct order from base to override file, so PhpStorm applies the same combination that a manual docker compose command with multiple -f flags would produce.

It is also worth explicitly entering values under Environment Variables that would otherwise only be resolved through the .env file, in case automatic resolution does not work. After adjustment, the configuration should be started once as a test and the actually used environment variables checked in the running container via the Docker tool window, to make sure the manual configuration really matches the expected combination.

# Run/Debug Configurations > Docker-Compose
# Compose files (order matters):
#   docker-compose.yml
#   docker-compose.dev.yml
# Environment variables (if .env is not auto-resolved):
#   PHP_VERSION=8.4
#   MYSQL_ROOT_PASSWORD=magento

8. Debugging Workflow: Xdebug With a Detected Compose Configuration

For PHP debugging inside a Docker Compose container, PhpStorm offers setting up a CLI interpreter of type Docker Compose that references the same compose file and the same service as the previously created run configuration. This interpreter appears under Settings, PHP, CLI Interpreters and can then be selected as the project interpreter for test runs and debugging sessions.

It is important that the path mappings between the local project directory and the path inside the container are entered correctly, otherwise breakpoints in the editor will not match the files actually executed inside the container. For automatically detected setups, PhpStorm usually derives path mappings from the compose file's volume definitions; for manually adjusted multi-file setups they should be rechecked after every change to the compose files.

9. Practical Setup and Comparison of Configuration Approaches

For a new project, it is worth letting automatic detection run first and starting the generated configuration as a test before making manual adjustments. This reveals which parts already work correctly and which actually need extra work, instead of manually configuring everything from scratch and leaving the built-in detection unused.

The table below compares automatic detection, partial manual adjustment and fully manual configuration in terms of effort and reliability at different levels of setup complexity. It shows that automation saves the full effort for simple projects, while multi-file setups like Magento's almost always require targeted adjustment of the compose files list and environment variables.

10. Summary

11. FAQ: Docker Compose Detection in PhpStorm: The Key Facts at a Glance