Magento Dev Environment in PhpStorm: Docker, CLI, Logs & Templates

1. Why PhpStorm makes a difference for Magento 2

Magento 2 is one of the most complex PHP frameworks on the market. Dependency injection, service contracts, plugins, observers, ViewModels and a deep directory tree with generated classes make manual navigation without IDE support inefficient. PhpStorm understands the Magento concept out of the box: the Magento PhpStorm Plugin (JetBrains Marketplace) offers navigation from XML configuration to classes, from interface declarations to concrete implementations, and from plugin definitions to the affected methods.

The decisive difference lies in how several features work together: a correctly configured Docker PHP interpreter ensures that code completion is based on the PHP actually running inside the container, including all Magento classes from vendor/ and generated/. Without this step, PhpStorm works with a local PHP installation that may run a different version and knows nothing about Magento's libraries. The result is incomplete autocompletion and missing type warnings exactly where they matter most.

Xdebug eliminates time-consuming var_dump debugging entirely. Set a breakpoint, trigger a request in the browser, and PhpStorm stops execution at the exact point, shows every variable with its current value, and lets you step through the Magento request flow. This is invaluable when it comes to understanding plugin chains, observer order and DI resolution.

2. Setting up Docker as the PHP interpreter

The first step is connecting PhpStorm to the running PHP container. Under Settings → PHP → CLI Interpreter → + → From Docker, Vagrant... you select the Docker service. In the Mark Shust setup that is the phpfpm container. PhpStorm reads the docker-compose.yaml in the project directory and lists all the defined services. After selecting phpfpm and clicking Detect, the IDE recognizes the PHP version, installed extensions and the path to php.ini.

Important: in the Path Mappings dialog, the local project path must be mapped to the container path. In the Mark Shust setup that is typically /home/user/development/project to /var/www/html. Without this mapping PhpStorm cannot find files inside the container and debugging fails. After saving, PhpStorm should show the correct PHP version in the PHP settings section, which for Magento 2.4.8 is PHP 8.4.

Once the interpreter is set up, PhpStorm indexes all PHP classes in the project, including vendor/. This first indexing run takes several minutes depending on project size. After that, Navigate-to-Class (Ctrl+N), Navigate-to-Symbol (Ctrl+Alt+Shift+N) and full code completion are available for every Magento class.

3. Configuring and using Xdebug with Docker

Xdebug is already available in the container in the Mark Shust setup and is enabled via the wrapper script bin/xdebug enable. On the PhpStorm side, the port must be set to 9003 (Xdebug 3) under Settings → PHP → Debug. The Debug Port must match the xdebug.client_port configured in xdebug.ini. In the Mark Shust environment the relevant configuration file can be found at env/php.ini.

For web debugging, enable the Listen for Debug Connections toggle in PhpStorm (phone icon in the toolbar or Ctrl+Alt+F5). In the browser you need an Xdebug browser extension (Xdebug Helper for Chrome/Firefox) that sets the debug cookie XDEBUG_SESSION. Alternatively the URL parameter ?XDEBUG_SESSION_START=PHPSTORM works as well. The first time a breakpoint is hit, PhpStorm asks for the path mapping again, so specify /var/www/html mapped to the local project directory once more.

; env/php.ini, Xdebug 3 configuration for Mark Shust Docker setup
[xdebug]
xdebug.mode = debug,develop
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.start_with_request = yes
xdebug.idekey = PHPSTORM
xdebug.log_level = 0

; For CLI debugging (bin/debug-cli enable)
; xdebug.start_with_request = trigger
; then use: XDEBUG_SESSION=1 bin/magento some:command

For CLI debugging with Magento commands, enable bin/debug-cli enable. After that, PhpStorm stops at set breakpoints during CLI runs of bin/magento commands. This is especially valuable when debugging upgrade scripts, data patchers and custom CLI commands. Important: run bin/xdebug disable after debugging, since Xdebug significantly affects performance while enabled.

4. CLI tools and run configurations

PhpStorm allows you to create run configurations that execute directly inside the container. Under Run → Edit Configurations → + → PHP Script you create configurations for frequently needed Magento commands. As the interpreter you select the Docker container, as the script /var/www/html/bin/magento, and as the parameter the desired command, for example cache:flush, setup:di:compile or indexer:reindex. These configurations are stored in the .idea directory and can be checked into the repository.

Even more productive is PhpStorm's Terminal feature (Alt+F12). The integrated terminal opens directly in the project directory and allows the use of every bin/ wrapper script without switching windows. PhpStorm colors terminal output and supports multiple parallel terminal tabs. The combination of run configurations for common commands and the integrated terminal for everything else covers the entire Magento CLI workflow.

5. Reading logs directly in PhpStorm

Watching Magento logs in var/log/ is unavoidable in day-to-day development. PhpStorm offers, via Run/Debug Configurations → Logs, the option to monitor log files directly inside the IDE. The relevant files are var/log/system.log, var/log/exception.log, and on Hyva projects also var/log/debug.log. PhpStorm opens a log tab that shows new entries in real time and can filter by search term.

Alternatively you can use the File Watcher feature, or simply the terminal with bin/log exception.log. For more structured log analysis, the PhpStorm Log File Viewer plugin is a good fit, as it renders JSON logs in a readable format. In Magento it makes sense to set the log level to DEBUG in the development environment to track every database query, cache operation and plugin call.

6. File templates for Magento artifacts

Magento artifacts follow strict conventions: ViewModels implement ArgumentInterface and use constructor property promotion, plugins must follow certain method prefixes, and repositories implement service contract interfaces. Typing these conventions by hand for every new file costs time and leads to careless mistakes. File templates in PhpStorm solve this: under Settings → Editor → File and Code Templates you create reusable templates with variables for namespace, class name and module prefix.

A ViewModel template already contains the correct namespace structure, the implements ArgumentInterface declaration, a sample constructor with property promotion and PHPDoc comments. When creating a new class via File → New → PHP Class (ViewModel), PhpStorm only asks for the class name and fills in every other field from the template. This reduces the time to create a new ViewModel from two minutes to ten seconds.

<?php
/**
 * ViewModel for ${NAME}
 *
 * Provides data and logic for ${NAME} template.
 * Implements ArgumentInterface as required by Magento ViewModel pattern.
 */

declare(strict_types=1);

namespace ${NAMESPACE};

use Magento\Framework\View\Element\Block\ArgumentInterface;

/**
 * Class ${NAME}
 *
 * @package ${NAMESPACE}
 */
class ${NAME} implements ArgumentInterface
{
    /**
     * ${NAME} constructor.
     *
     * @param \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig
     */
    public function __construct(
        private readonly \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig,
    ) {}

    /**
     * Example method, replace with actual business logic.
     *
     * @return bool
     */
    public function isEnabled(): bool
    {
        return (bool) $this->scopeConfig->getValue(
            'mironsoft_module/general/enabled',
            \Magento\Store\Model\ScopeInterface::SCOPE_STORE,
        );
    }
}

7. Live templates for recurring patterns

Live templates (snippets) are the next productivity step after file templates. While file templates generate complete files, live templates insert code fragments at the cursor position. In PhpStorm, under Settings → Editor → Live Templates, you create groups for Magento and fill them with commonly needed patterns. The abbreviation mvm expands to a full ViewModel constructor with property promotion, mpl to a plugin method signature with a before/after prefix, and mobs to an observer skeleton.

Live templates support variables and functions. The variable $CLASS_NAME$ can be filled in automatically from the current class name, and $DATE$ inserts the current date. Particularly useful is the live template for Magento logger calls: mlog expands to $this->logger->debug(__METHOD__ . ': ', ['data' => $variable]);, complete with __METHOD__ context, which immediately shows which method an entry came from when reading the log later.

8. Code style and inspections for Magento

Magento follows the PSR-2 standard with a few project-specific extensions. In PhpStorm, under Settings → Editor → Code Style → PHP, you import the Magento code style scheme, which is available in the Magento repository as .phpstorm.meta.php and a PhpStorm settings file. The Reformat Code setting (Ctrl+Alt+L) then formats every file consistently according to the Magento standard. For automatic formatting on save, enable Actions on Save → Reformat code.

You can extend PhpStorm's PHP Inspections with the PHP Inspections (EA Extended) plugin from the JetBrains Marketplace. This plugin recognizes Magento-specific anti-patterns: direct object instantiation instead of dependency injection, a missing declare(strict_types=1) declaration, and overly broad exceptions in catch blocks. Seeing these warnings directly in the editor, before PHPStan reports them during a CI run, significantly speeds up development.

9. Workflow comparison: with and without a PhpStorm setup

The difference between an unconfigured PhpStorm and a fully set up Magento environment is measurable. While you have to manually search for a file in the Finder or Explorer for every class navigation without configuration, Navigate-to-Class jumps to the target in milliseconds. Xdebug replaces hours-long var_dump sessions with targeted breakpoints.

Add up these savings over a typical workday with five to ten debugging cycles, a handful of new classes and numerous cache flush operations, and you quickly arrive at one to two hours a day gained through a correctly configured PhpStorm environment. Over weeks and months this is a substantial productivity gain that amortizes the setup time many times over.

10. Summary

A fully set up PhpStorm environment for Magento 2 consists of several layers that together produce a substantial productivity advantage. The Docker PHP interpreter ensures that code completion and type checks are based on the PHP version actually in use. Xdebug replaces tedious var_dump debugging with precise breakpoints and full variable inspection. Run configurations make frequent Magento commands accessible with a single keystroke. File templates guarantee that new artifacts follow Magento conventions from the start.

The effort for the initial setup is one to two hours. After that, this effort pays for itself every day through saved debugging time, faster navigation and fewer convention errors. Anyone who checks the settings, run configurations, code style profiles and file templates, into the repository's .idea directory passes this productivity gain on to every team member without each person having to go through the setup themselves.

11. FAQ: PhpStorm Magento Dev Environment