Phpstorm And Docker
PhpStorm has had Docker support for a while now, and using a Docker remote interpreter has been a relatively straightforward task for the last few releases. PhpStorm 2017.2 introduces native support for Docker Compose to make using Docker and PhpStorm even easier. Working with Docker in PhpStorm Running the Docker from PhpStorm. As all the tools are installed, and the integration is configured, the recently created Start Docker Run/Debug Configuration can be launched. The Application Servers tool window will be opened updating you on the provisioning status and current state of all your Docker containers:. As soon as the process is completed, and our. I wanted to run tests with PHPUnit on a docker environment, which was set up with docker-compose, and use the PhpStorm integration. Since PhpStorm 2013.2 there is a docker intergration which works well for single containers, but unfortunately it does not seem to use the running network of containers. So for example my PHP container does not get access to the MySQL container for integration tes. It's the next video in a series about the usage of PHPUnit and various interpreters in PhpStorm. Here Gary Hockin, PhpStorm Developer Advocate, explains how.
So, you’ve decided to try something new today and started a project from scratch. Your first step will be to set up a development environment: at the bare minimum, you’d want to run a web server and a PHP interpreter (preferably – with the debugging engine installed).
With Docker, you can start developing, running, and debugging your code in a matter of minutes!
Probably the easiest way to integrate Docker with PhpStorm is to use the PhpStorm Docker registry. It provides a selection of preconfigured Docker images curated by the PhpStorm team, which cover the most common PHP development needs.
Before you proceed, make sure that you have Docker installed on your machine: see how to do it on Windows and on macOS.
Defining the environment
To get started, we create a new project in PhpStorm. Next, we create a new file named docker-compose.yml , which will describe the configuration of the services comprising our app. In our case, it will be a single webserver service:
As you can see, we use the preconfigured Docker image comprising the Apache web server and PHP 7.1 with Xdebug.
Note that we use the host.docker.internal value to refer to the remote host. In Docker for Windows and Docker for Mac, it automatically resolves to the internal address of the host, letting you easily connect to it from the container.
An important note for Linux users: host.docker.internal on Linux is currently not supported. You’ll have to use your local machine’s hostname instead (to find out what your machine’s hostname is, simply execute hostname in Terminal).
The corresponding environment configuration section for Linux will read as follows:
See here for more details and possible workarounds.
Our environment is fully described:
We can now start using it by creating a dedicated run/debug configuration.
Creating a run/debug configuration
Right-click docker-compose.yml and select Create… from the context menu:
Phpstorm Docker Machine
In the dialog that opens, provide the name of the configuration and apply your changes:
You can now start the configuration from the toolbar:
PhpStorm will automatically download the required image and start the web server:
That’s it: we’ve got everything ready for running and debugging our code!
Running and debugging code
Let’s ensure that everything works as expected. To do this, we’ll create the most simple Hello world PHP file and try to debug it following the PhpStorm Zero-Configuration Debugging approach.
Since we already have Xdebug installed and configured, this will only require that you:
- Have a debugging extension installed and enabled for your browser:
- Set a breakpoint in your code:
- Enable listening to incoming debug connections in PhpStorm:
Now, simply open the page in the browser, and the debugging session will be started automatically:
We encourage you to further explore the PhpStorm Docker registry: while we’ve looked at a very simple case, you can use the described technique to provide your environment with, for example, a database, or an sftp server.
Using these Docker images will save you a lot of effort and let you start coding in a matter of a minute, or even less!
If you’d like to learn more about Docker and how to use it in PhpStorm, make sure to check out the excellent tutorial series by Pascal Landau, and PhpStorm documentation, of course.
Your JetBrains PhpStorm Team
The Drive to Develop
To follow this tutorial, you must have the Xdebug extension installed on your container. In my example, I will use a Docker image of TheCodingMachine created by David Négrier. If you are starting a project, I recommend you to download one of our images here TheCodingMachine Docker PHP images
My base docker-compose.yml file looks like this:
Note: the PHP_EXTENSION_XDEBUG environment variable is specific to the thecodingmachine/php. It automatically configures Xdebug for the container.
Ports configuration
Keep in mind that PHPStorm opens port 9000 (by default) so Xdebug can connect to it. Our PHP container has Xdebug installed and Xdebug will try to connect to PHPStorm on port 9000 by default.
Out of the box, everything should be fine...
... except if port 9000 is already taken by another program on your host (your machine running PHPStorm).
Switching port
Port 9000 can be already used. In particular, if you are using PHP-FPM, the default port for PHP-FPM is 9000.This directly conflicts with the XDebug port.
If you want to use another port for Xdebug, follow the instructions below.
I recommend to use port 10000 instead.
Otherwise, just keep the default configuration port.
Registering your container server in PHPStorm
First, click on edit configurations, on the top right of PHPStorm window.
Then, follow the explanation in picture. All numbers are explained below.
(1) Click on add button
(2) Confirm it by clicking on PHP Web Page
(3) Define a name for your project
(4) Click on ... to add a debug server
(5) Once it's done, you are on debug server page. Click on '+' button to create a new one.
(6) Define a server name like docker_[your_project_name]
(7) Add your host on port 80 using Xdebug
(8) Don't forget to click on Use path mappings
(9) We need to add path mapping. Indeed, from the point of view of Xdebug, the PHP application runs in the '/var/www/html' (we are in a container!).But for PHPStorm, my project is in my host machine directory! So we need to map the root of your PHP application to the '/var/www/html' directory, as shown on the image above.
At this point, you should be able to put a breakpoint in your code, start a debugging session and get the application to stop on the breakpoint. Jump to chapter 'Run Xdebug' to see how to use Xdebug.
Xdebug CLI
All applications are not web-based. You might also want to debug a command-line application, from within your container.Let's see how to enable Xdebug for scripts (CLI)
In the docker-compose.yml, just add those environment variables
Remember that we are using our technical director's (David Négrier) images. That's why we can set PHP extensions, PHP .ini configurations into the docker-compose.yml.For more details, please look at this TheCodingMachine Docker PHP images.
(1) Enable the Xdebug extension
Docker Xdebug
(2) If you are using a different Xdebug port, set your custom Xdebug port
(3) Add your Xdebug server name
(4) If you are using the default Xdebug port, please remove remote_port=[your_xdebug_port]. Otherwise, add your custom Xdebug port
Run Xdebug
Web
Place a breakpoint in your code and launch a debug session
A new windows should open and you should access to PHPStorm debug bar.
Scripts (CLI)
Click on Start Listening for PHP Debug connections
The button should appear like this :
Place a breakpoint in your code.
Now, just go into your php-apache container using docker exec -ti [container_id] bash and run your script manually.
Addentum: Installing Docker integration in PHPStorm
There is a very useful PHPStorm extension to quickly and efficiently manage your docker containers.
For example:
- see the logs by container
- have access to bash in a clique
- quickly see environment variables
- clear or restart containers
Before starting
- You should check that the 'Docker integration' is enabled on your IDE
- Start the Docker daemon on you machine
- Move to your favorite Docker project in PHPStorm
Configuring Docker
Now everything should be good, just go to Preferences... > Languages and Frameworks > PHP
(1) Click on ... for openning the remote PHP interpreter
(2) Add a new CLI interpreter by clicking on From Docker, Vagrant, VM, Remote...
(3) Click on Docker (remember that you should start Docker daemon)
(4) Add a new server
(5) Select a server name
(6) Choose how to connect on Docker
(7) Make sure the connection is successful
(8) Select your favorite default image
(9) You need to set the path mapping for your code. By default, it's /opt/project in the container, just change it to /var/www/html
Done! Just click on the Docker button on the bottom of PHPStorm window.
About the author
Alexis is an experienced technical project manager who manages several projects including Eco-Emballages (CITEO). Graduate of EPITECH, Alexis is specialized in PHP frameworks (Symfony, Laravel, Mouf) and he masters Docker.
Related articles
Latest articles
Open-source matters
At TheCodingMachine, we are using open-source tools daily to build our projects. And since we and our clients are ripping huge benefits from these open-source products, we also try to 'give back' to the open-source community.
Freelance Developer?
At TheCodingMachine, we are always looking for top freelance developers to work with us on our next state-of-the-art project.
Interested in developing quality projects? We love good work and we pay fairly.
How Docker Works
We are hiring!
Phpstorm Docker
Living in France? We are actively looking for developers and project leaders in our Paris and Lyon office.
About us
At TheCodingMachine, we strive to develop websites , extranets, intranets and business web applications in PHP and JavaScript for a wide range of clients.
Do not hesitate to contact us!
Best practices
When writing code, we expect it to be of the best possible quality. To enforce this quality, we redacted our own 'best practices' described in a dedicated website.
We are happy to share those with you!
Packanalyst
We are the happy parents of Packanalyst, a free online service that lets you search any possible PHP class or interface referenced on Packagist.
Pretty useful for open-source developer to keep an eye on who is using what class/interface of your packages.