Productive PHPStorm Checklist for Docker, Magento and PHP Projects

1. Why a checklist for PHPStorm?

PHPStorm is one of the most powerful IDEs for PHP development, but it only unfolds its full value with the right configuration. In Docker-based projects, especially with Magento 2, there are numerous places where a wrong or missing setting massively reduces productivity. Autocomplete does not work because the interpreter points to the local machine instead of the container. Xdebug does not start because the port is blocked. The IDE becomes slow because thousands of vendor files are unnecessarily indexed.

This checklist bundles all the critical settings in the order that matters most for a Docker Magento project. It is not meant as a one-time setup guide, but as a reference to work through with every new project setup or new team member. Every point is given with the concrete PHPStorm path and the setting, so no guessing is needed.

2. PHP interpreter: configuring remote vs. local correctly

The most important point on any PHPStorm checklist for Docker projects is the PHP interpreter. PHPStorm needs the interpreter for autocomplete, type inference, static analysis and run configurations. In a Docker setup there are two sensible approaches: either a Docker-based interpreter that runs directly inside the container, or an SSH-based remote interpreter for more complex setups.

For Mark Shust Docker setups, the Docker Compose interpreter is the recommended option. The path to get there: Settings → PHP → CLI Interpreter → + → From Docker, Vagrant, VM, WSL, Remote.... Server: Docker Compose, configuration file: compose.yaml, service: phpfpm. PHPStorm then starts a temporary container to determine the PHP version and extensions. After that, all autocomplete information is available based on the actual container PHP, not based on the local PHP, which may have a different version or different extensions.

<?php
// PHPStorm path mapping check, verify container path resolution
// Settings → PHP → CLI Interpreter → Remote → Path Mappings

// Local:     /home/mir/development/mironsoft/src
// Container: /var/www/html

// Test: create a simple PHP file and check if PHPStorm resolves
// the path correctly when Xdebug hits a breakpoint

declare(strict_types=1);

// If autocomplete works for this class, interpreter is correct
$objectManager = \Magento\Framework\App\ObjectManager::getInstance();

// PHPStorm should show full type info for $objectManager
// if vendor/ is indexed and interpreter points to container

A common mistake on the checklist: path mappings are forgotten. PHPStorm needs to know that /home/mir/development/mironsoft/src locally corresponds to the container path /var/www/html. Without these mappings, Xdebug works, but PHPStorm does not open local files when stopping at a breakpoint. The mappings are configured in the interpreter dialog under "Path Mappings" and should be set up for all relevant directories.

3. Indexing: excluding vendor and generated sensibly

The biggest performance problem in PHPStorm with Magento 2 is indexing. Magento has a massive vendor/ folder and also generates code into generated/. Without exclusions, PHPStorm tries to index everything, which for Magento 2 means several gigabytes of PHP code. The result: a sluggish IDE, long startup times and an overheated laptop.

The checklist for indexing exclusions with Magento 2: Settings → Project → Directories. Mark the following directories as "Excluded": var/, pub/static/, generated/, pub/media/. The vendor/ folder should not be fully excluded, PHPStorm needs it for autocomplete. But vendor/magento/framework/generated/ and similar generated subfolders can be excluded. Alternatively: mark vendor/ as "Library Root" instead of "Source Root", so it is used for autocomplete but not analyzed as aggressively.

<?php
// .idea/mironsoft.iml, PHPStorm project structure
// Directories excluded from indexing (XML configuration)

/*
<component name="NewModuleRootManager">
  <content url="file://$MODULE_DIR$">
    <sourceFolder url="file://$MODULE_DIR$/src/app/code" isTestSource="false" />
    <excludeFolder url="file://$MODULE_DIR$/src/var" />
    <excludeFolder url="file://$MODULE_DIR$/src/pub/static" />
    <excludeFolder url="file://$MODULE_DIR$/src/pub/media" />
    <excludeFolder url="file://$MODULE_DIR$/src/generated" />
  </content>
</component>
*/

// Also exclude in Settings → Editor → File Types → Ignore files and folders:
// Add: *.min.js, *.min.css, node_modules, .git (already excluded by default)

// Memory settings: Help → Change Memory Settings
// Recommended for Magento: 4096 MB heap

4. Configuring Xdebug reliably with Docker

Xdebug is on every PHP developer's checklist, but configuring it with Docker has specific pitfalls. The most common problem: Xdebug inside the container cannot reach the IDE on the host, because the Docker network configuration does not resolve the hostname. On Linux, the host is reachable from the container via the Docker gateway IP, while on macOS and Windows host.docker.internal works out of the box. On Linux you have to explicitly determine the gateway IP or define host.docker.internal via extra_hosts in the compose file.

The complete Xdebug checklist for Docker: first set xdebug.client_host to the correct host IP in the container configuration. Then in PHPStorm under Settings → PHP → Debug set the port to 9003 (Xdebug 3). Under Settings → PHP → Servers create a server with the correct hostname and path mappings. Enable the debug listen button in PHPStorm (the phone icon in the toolbar). Then trigger a request in the development environment with the Xdebug cookie or IDE key.

<?php
// docker/phpfpm/xdebug.ini, Xdebug 3 configuration for Docker
/*
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
xdebug.idekey=PHPSTORM
xdebug.log_level=0
xdebug.max_nesting_level=512

; For Linux: use host-gateway instead of host.docker.internal
; Add to compose.yaml under phpfpm service:
; extra_hosts:
;   - "host.docker.internal:host-gateway"
*/

// PHPStorm Settings → PHP → Debug:
// Debug port: 9003
// Check: "Can accept external connections"

// PHPStorm Settings → PHP → Servers:
// Name: mironsoft-docker
// Host: localhost
// Port: 80
// Debugger: Xdebug
// Path Mapping: /home/mir/development/mironsoft/src → /var/www/html

5. Run configurations for Magento CLI and PHPUnit

Run configurations are often underestimated on the PHPStorm checklist. Instead of always typing commands in the terminal, run configurations enable a one-click start for frequent tasks: flushing the Magento cache, running setup upgrade, starting tests. In Docker projects you use "Shell Script" run configurations for this, calling the wrapper scripts in the bin/ directory, or PHP run configurations with the remote interpreter.

The checklist for PHPUnit in Docker: Run → Edit Configurations → + → PHPUnit. Test runner: PHPUnit via Composer. Interpreter: the Docker Compose interpreter. Configuration file: src/dev/tests/unit/phpunit.xml. Working directory: /var/www/html (container path). After the first start, PHPStorm saves the configuration, so future runs start via the run bar or with Shift+F10. For individual test classes, you can call "Run ..." directly from the editor context menu.

<?php
// .idea/runConfigurations/Magento_Cache_Flush.xml
/*
<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Magento: Cache Flush"
                 type="ShellScriptRunConfigurationType">
    <option name="SCRIPT_PATH" value="$PROJECT_DIR$/bin/magento" />
    <option name="SCRIPT_PARAMETERS" value="cache:flush" />
    <option name="INTERPRETER_PATH" value="/usr/bin/env" />
    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
  </configuration>
</component>
*/

// Useful Run Configurations for Magento 2:
// 1. bin/magento cache:flush
// 2. bin/magento setup:upgrade --keep-generated
// 3. bin/magento setup:di:compile
// 4. PHPUnit: Unit Tests
// 5. PHPUnit: Integration Tests (separate config)
// 6. bin/phpcs app/code/
// 7. bin/phpstan analyse app/code/

6. Plugins: what actually helps and what slows you down

On the PHPStorm checklist for plugins, the rule is: less is more. Every plugin that is active without being used burdens the indexing process and slows down the IDE. The first task is therefore to disable all pre-installed plugins that are not needed in the project: CVS, Subversion, Mercurial (if only Git is used), CoffeeScript, Haml, Stylus, and similar ones.

Plugins that are genuinely useful for PHP Docker Magento projects: PHP Annotations (autocomplete for Magento DI annotations), Symfony Support (also works for Magento DI, since the principles are similar), GitToolBox (inline git blame), .env files support. Optional: PHPStan for PHPStorm, if PHPStan should not run via External Tools. Not recommended for Magento: Magento-specific plugins, which are often no longer maintained and create compatibility problems. PHPStorm's native indexer generally handles Magento structures well.

7. Code style, EditorConfig and inspections

Code style in PHPStorm is important on the checklist for team consistency. PHPStorm reads .editorconfig files automatically and applies the settings defined there for indentation, line endings and encoding. For Magento 2 projects: 4 spaces indentation, UTF-8, Unix line endings. The .editorconfig file sits in the project root and is read by PHPStorm without additional configuration as soon as the EditorConfig plugin is active (enabled by default).

Inspections are configured under Settings → Editor → Inspections → PHP. For productive work it is recommended to set all PHPStan and PHP-CS-Fixer inspections to "Warning" instead of "Error", so the editor does not turn red whenever PHPStan issues a warning. The actual quality check then runs via External Tools or run configurations, not as a live inspection. This significantly reduces "warning noise" and makes the editor pleasant to use again.

8. Checklist comparison: common mistakes vs. best practice

9. Summary

A productive PHPStorm environment for Docker, Magento and PHP projects does not come from a default installation, but from systematically working through the checklist. The remote interpreter based on Docker Compose ensures that autocomplete and type inference are based on the actual container PHP. Correct indexing exclusions prevent PHPStorm from choking on Magento's vendor bulk. Xdebug with the correct client_host and path mappings makes debugging reliable. Run configurations replace repeated typing in the terminal.

10. FAQ: PHPStorm checklist for Docker, Magento and PHP