PhpStorm Docker proxy

Run PHP from PhpStorm inside an existing Docker container.

Contents

• Requirements
• Installation
  • 1. Get the phar
  • 2. Create the config file
  • 3. Configure PhpStorm to use the proxy
• List of configuration directives
• Troubleshooting tips
• How does it work
• Building the phar

Requirements

• PHP 8.1+ (installed locally)
• Docker
• PhpStorm

Installation

1. Get the phar

Download the latest phar from releases.

You can also build your own. See Building the phar.

Tip

An alternative is to clone this repository and use bin/phpstorm-docker-proxy instead of phpstorm-docker-proxy.phar.

You will need Composer to install dependencies.

2. Create the config file

Create a file called .phpstorm-docker-proxy.json in your project's root (or any parent directory) with the following contents:

{
    "image": "php_image_name_here",
    "paths": {
        "./app": "/var/www/html"
    }
}

• change php_image_name_here to the name of your project's PHP Docker image (i.e. an image that contains a php binary executable from CLI). If you prefer you can use the container settings to use a specific container instead.
• update paths to map local paths into the container (according to your docker volumes)

See more options in List of configuration directives.

3. Configure PhpStorm to use the proxy

1. make sure the container specified in the configuration is up and running
2. head to File - Settings - Languages & Frameworks - PHP
3. click the "..." on the right side of CLI Interpreter
4. click the "+" to add a new interpreter as Other Local...
5. set PHP executable to a full path to phpstorm-docker-proxy.phar
6. PhpStorm should check and display the expected PHP version

See Troubleshooting tips if you have any issues.

Note

On Windows, unless you have configured .phar files to be executable, you will need to create and use a batch script instead of the phar as PHP executable.

Example of phpstorm-docker-proxy.bat (assuming phar in the same dir):

@echo off
php %~dp0phpstorm-docker-proxy.phar %*

List of configuration directives

The following directives are supported in .phpstorm-docker-proxy.json:

Option	Default	Description
image	-	PHP Docker image name
container	-	PHP Docker container name
paths	{}	Host to container path mapping. host paths are relative to the config file container paths should be absolute trailing slashes should be omitted
phpBin	"php"	PHP binary name or path inside the container.
dockerBin	"docker"	Docker binary name or path on host.
directorySeparator	"/"	Directory separator inside the container.
debug	false	Toggle debugging output.

Troubleshooting tips

• make sure the configured Docker container is running
• make sure the version of the tool you're using (e.g. PHPUnit) is properly detected in PhpStorm settings
• try to run a plain PHP script (using Run - Run...) and check the output for errors
• add "debug": true to configuration to display additional information

How does it work

This tool uses docker exec to proxy PHP calls from PhpStorm into a running Docker container.

The rough workflow is as follows:

1. locate and load configuration file from working directory or above
2. parse the provided PHP arguments
3. extract IDE_* environment variables and replace paths in them
4. process the PHP arguments so they're valid inside the container
5. locate a running container using the image name from configuration
6. run docker exec with appropriate options and arguments

Building the phar

Use the build-phar.sh script (available in source). You need to have Box installed (either globally or as box.phar in the project's root directory).

bin/build-phar.sh