Run Configurations in PhpStorm for PHPUnit, Magento CLI and Custom Commands

1. Why run configurations are more than a terminal replacement

Run configurations in PhpStorm are not simplified terminal shortcuts. They are fully parameterizable execution contexts that combine interpreter, working directory, environment variables, before-launch tasks and debugging integration into a single, reusable profile. Anyone who types Magento CLI commands day to day has to remember syntax, paths and Docker wrappers every single time. With a run configuration this shrinks to a single keypress, and the workflow is always correct and reproducible.

The crucial difference from the terminal lies in the Xdebug integration. A PHPUnit test executed as a run configuration can be started with the green debug button: PhpStorm stops at every breakpoint, shows the call stack, the current variable values and allows step-through debugging. For tests running in the terminal this is not possible without manual XDEBUG_MODE configuration. Run configurations abstract this complexity away entirely.

For teams, the biggest advantage is shareability. Run configurations can be versioned as XML files in the .idea/runConfigurations/ directory. After a git clone, every developer immediately has all configurations available, no README instructions, no copying commands, no errors caused by slightly different terminal setups. That alone justifies the one-time investment in cleanly set up run configurations.

2. Understanding the basic structure of a run configuration

PhpStorm knows several run configuration types that differ in their target domain: PHP Script for direct PHP files, PHPUnit for the test runner, Shell Script for bash scripts and Compound for running several configurations sequentially or in parallel. Every type shares common base fields: name, interpreter (local or remote), working directory and environment variables.

The interpreter is the central element of every PHP-based run configuration. In a Docker environment following the Mark Shust pattern, PHP runs inside the container, not on the host. PhpStorm lets you define a remote interpreter that communicates via Docker, Docker Compose or SSH. Once this interpreter is set up, every run configuration referencing it automatically uses the container's PHP version and PHP extensions, identical to the production environment.

The working directory of a run configuration determines from where relative paths are resolved. For Magento projects this is always the Magento root directory inside the container, typically /var/www/html. If it is set incorrectly, the autoloader and configuration paths fail silently. When setting up a run configuration for the first time, always specify the working directory explicitly, never rely on the default.

3. PHPUnit configuration with the Docker remote interpreter

A PHPUnit run configuration for Magento with Docker requires three prerequisites: a configured remote interpreter, a phpunit.xml file in the project directory and the PHPUnit autoloader. In PhpStorm you open Run → Edit Configurations → + → PHPUnit. As the interpreter, select the Docker interpreter that points to the phpfpm service of the Magento Compose stack. The test scope can be set to a single class, a directory or the full phpunit.xml configuration.

The phpunit.xml for Magento integration tests points to Magento's bootstrap file. This is the most common setup mistake: PHPUnit cannot find the bootstrap because the path is specified relative to the host instead of the container file system. With a remote interpreter, all paths in phpunit.xml are interpreted as container paths. This means the XML file must use container paths (/var/www/html/dev/tests/...), not host paths.

<!-- phpunit.xml for Magento 2 unit tests in PhpStorm with a Docker interpreter -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
    bootstrap="/var/www/html/app/autoload.php"
    cacheDirectory="/var/www/html/var/.phpunit.cache"
    colors="true">

    <testsuites>
        <testsuite name="Mironsoft Unit Tests">
            <directory>/var/www/html/app/code/Mironsoft/*/Test/Unit</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory>/var/www/html/app/code/Mironsoft</directory>
        </include>
        <exclude>
            <directory>/var/www/html/app/code/Mironsoft/*/Test</directory>
        </exclude>
    </source>

    <php>
        <env name="MAGENTO_FRAMEWORK_MODULE_PATH"
             value="/var/www/html/vendor/magento/framework"/>
    </php>
</phpunit>

Once the run configuration is saved, it appears in the run dropdown in the top right. Pressing Ctrl+Shift+F10 starts the run configuration for the currently open test file. PhpStorm recognizes PHPUnit test classes and displays green run icons in the gutter next to every test method, one click starts exactly that single test. This saves considerable time compared to running the entire test suite.

4. Magento CLI commands as a run configuration

Magento CLI commands such as setup:upgrade, cache:flush or custom commands from your own modules can be stored as PHP Script run configurations. The trick is to specify bin/magento as the PHP file instead of a custom script, and pass the desired command as an argument. With the Docker remote interpreter, the command runs directly inside the container, exactly like bin/magento cache:flush in the terminal, but without opening the terminal.

For frequently used commands, a collection of named run configurations is recommended: Magento: Cache Flush, Magento: Setup Upgrade, Magento: DI Compile. These can be listed via Run → Run… or the shortcut Alt+Shift+F10 and started with a single keypress. Particularly practical is the option to create separate configurations with different --env arguments, for example a dedicated run for setup:static-content:deploy de_DE with the -f flag.

<?php
// .idea/runConfigurations/Magento_Cache_Flush.xml
// This file is read automatically by PhpStorm and shown as a run configuration.
// Version control: check this file into the Git repository!

/*
<component name="ProjectRunConfigurationManager">
  <configuration default="false"
                 name="Magento: Cache Flush"
                 type="PhpScriptRunConfigurationType"
                 factoryName="PHP Script">
    <option name="path" value="$PROJECT_DIR$/src/bin/magento" />
    <option name="arguments" value="cache:flush" />
    <option name="workingDirectory" value="$PROJECT_DIR$/src" />
    <method v="2">
      <option name="com.jetbrains.php.run.script.PhpScriptBeforeLaunchTask"
              enabled="false" />
    </method>
  </configuration>
</component>
*/

5. Managing environment variables and secrets securely

Run configurations support environment variables in two ways: directly in the configuration dialog under Environment variables or via a .env file that PhpStorm reads. For secrets such as database passwords or API keys, entering them directly in the dialog is problematic, since the values are stored in the XML configuration file, which ends up in the repository. The secure approach is to use placeholders that reference system environment variables: $DB_PASSWORD is replaced at runtime with the value from the shell session.

Since version 2023.1, PhpStorm supports direct integration of .env files. In the run configuration dialog under Environment variables → …, a .env file can be specified. This file should be listed in .gitignore and exist only locally. The pattern is identical to what Docker Compose uses for env_file entries, so anyone already managing their Docker Compose environment variables in a .env file can use the same file in run configurations.

A clean structure for Magento projects: an env/phpstorm.env file contains all the values run configurations need, database connection, Magento base URL and debug flags. This file is listed in .gitignore. The repository contains an env/phpstorm.env.example as a template with dummy values. New developers copy the file, adjust the values, and all run configurations work immediately without manual adjustment.

6. Compound run configurations for complex workflows

Compound run configurations combine multiple individual configurations and start them either sequentially or in parallel. The typical Magento use case: a Deploy Sequence compound that first runs Magento: DI Compile, then Magento: Setup Upgrade and finally Magento: Cache Flush. Instead of typing three separate commands in the terminal or calling a shell script, a single click is enough, and PhpStorm displays the output of each step clearly in its own tabs.

Compound configurations are especially valuable for test setups. An All Tests configuration can start unit tests and integration tests in parallel and display both results at the end. PhpStorm does not aggregate the test results, but each run has its own output tab. If one of the runs fails, it is immediately obvious which configuration is responsible, without having to search through the output.

7. Shell script configurations and before-launch tasks

Besides PHP configurations, PhpStorm also supports shell script configurations. These let you start bash scripts, for example bin/cache-clean or custom deploy wrappers, directly from the IDE. Configuration happens under + → Shell Script. /bin/bash can be specified as the interpreter, and the absolute path to the script as the script path. For Docker-based setups following the Mark Shust pattern this is ideal: the bin/ wrapper scripts that run commands inside the container can be stored as shell configurations.

Before-launch tasks make it possible to start another configuration before the main run. This is practical for test runs: before the PHPUnit run, a Magento: Cache Clean task is automatically executed to guarantee a clean starting state. Before-launch tasks are configured at the bottom of the configuration dialog, and any number of tasks can be added using the plus icon. External tools such as composer install or CSS build processes can also be wired in as before-launch tasks.

<?php
// Example: a custom Magento CLI command as a run configuration target
// app/code/Mironsoft/Catalog/Console/Command/SyncProducts.php

declare(strict_types=1);

namespace Mironsoft\Catalog\Console\Command;

use Magento\Framework\Console\Cli;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Console command to sync product data from external source.
 * Run via PhpStorm: bin/magento mironsoft:catalog:sync-products --limit=100
 */
final class SyncProducts extends Command
{
    private const OPTION_LIMIT = 'limit';

    public function __construct(
        private readonly \Mironsoft\Catalog\Api\ProductSyncServiceInterface $syncService,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setName('mironsoft:catalog:sync-products')
            ->setDescription('Sync products from external catalog API')
            ->addOption(self::OPTION_LIMIT, null, InputOption::VALUE_OPTIONAL, 'Max products to sync', 500);
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $limit = (int) $input->getOption(self::OPTION_LIMIT);
        $output->writeln(sprintf('<info>Syncing up to %d products...</info>', $limit));
        $synced = $this->syncService->sync($limit);
        $output->writeln(sprintf('<info>Done. Synced: %d</info>', $synced));
        return Cli::RETURN_SUCCESS;
    }
}

8. Debugging directly through the run configuration

Debugging via run configurations is the strongest advantage over the terminal. Instead of manually setting XDEBUG_MODE=debug php bin/magento ..., it is enough to click the debug button (green bug icon) instead of the run button. PhpStorm automatically sets the required Xdebug environment variables for the remote interpreter and waits for the connection. Breakpoints in any PHP file, including Magento core files in the vendor/ directory, are reliably hit.

For PHPUnit debugging this is especially valuable. A test producing an unexpected error can be stepped through with a single debug run. The call stack shows exactly which methods were called in which order. Variable inspection reveals the exact state of the object at the moment of the error, without a single var_dump needing to be inserted into the code. This shortens the debugging cycle from minutes to seconds.

9. Comparing run configuration types

Choosing the right run configuration type is crucial for functionality. Each type offers different options and is suited to different scenarios in everyday Magento development.

For Magento projects, the PHPUnit and PHP Script types are the most important. They fully benefit from the remote interpreter and the Xdebug integration. Shell script configurations are useful for build processes that run outside the PHP container, for example the Tailwind CSS build process. Compound configurations bundle everything into a one-click workflow.

10. Summary

Run configurations in PhpStorm are the link between the IDE and the running Magento Docker stack. With a correctly configured remote interpreter, PHPUnit tests can be started and debugged with a single keypress. Magento CLI commands are stored as PHP Script configurations and never need to be typed into the terminal again. Compound configurations bundle deploy workflows into reproducible one-click flows.

The most important step is versioning the configurations. Checking the XML files in the .idea/runConfigurations/ directory into the repository ensures that every developer has the same starting point. Environment variables and secrets stay local via .env files, while the configuration structure itself is shared. The result is an IDE setup that gets new team members productive after a single git clone.

11. FAQ: Run Configurations in PhpStorm