It is possible to run PHP cli without a docker-compose file, I have found it is easier to set up PhpStorm using this intermediate step. PhpStorm has several preconfigured Docker containers, source: Github - JetBrains / phpstorm-docker-images; Docker hub - PhpStorm; They can be used as follows: Php 7.3 CLI and XDebug 2.7. Apparently, XDebug is not installed at all with Laravel Sail. In order to include it, you have to modify the Dockerfile, edit docker-compose.yml and rebuild the containers. Here is how I did. I copied the Docker configuration Laravel Sail uses in a more convenient place.
This post was cross posted on Dev.to
Docker has changed dramatically the way we develop applications. Thanks to it, it is really easy for everyone to run a complex application with a single command, without having to worry about the inner details like dependencies. These advantages are even greater when working on a team or enterprise context. I still remember being like the first 3 days when I joined my current company, configuring the project and all the related libraries and tools. Docker make it such much easier, faster and consistent.
But everything comes with a price. There is an extra complexity of maintaining all the Docker stuff. Also some things that were very easy in a normal development environment running locally, like debugging your application from your IDE, now requires some extra configuration. And in case of getting Xdebug to work, its not an easy task. I couldn't find a single guide that have all the steps from start to finish. Thats why I decided to write this article. It will guide you to step by step through the process of installing and configuring Xdebug and PHPStorm with a Dockerized Symfony 4 application.
Pre-requisites
- This was tested on an Ubuntu 18.04 machine with PHPStorm 2018.1.4 and latest versions of Docker and Docker Compose. Some things might work a little different in other Operating Systems.
- I assume you have a basic Knowledge of Docker, PHP and XDebug.
- You can clone this repository as base to follow this gude as it contains a basic Symfony Flex application with all the Docker stuff explained in this article included.
Step 1 - Dockerize the application
Of course, to be able to use Xdebug you must install it on your Docker container.The way to do this, will depend of your base image. I always use alpine based images. I wont enter in detail about how to Dockerize a Symfony application. You can follow along with the Dockerfile included in the demo repository.
Here is the relevant excerpt of the Dockerfile that installs Xdebug:
I dont want have to have a separate Dockerfile for development and production, so I have defined a build argument that will tell whether we want to install Xdebug or not.
Then, on my Docker-compose file I have the following definition for my application:
See for the full docker-compose file.
Nothing really fancy about this. The important bit is the 'env_file' instruction which tells Compose to load environment variables from a '.env' file, which is the standard way for Symfony 4 applications.
We will use that file to add some required environment variables for Xdebug. If you prefer in you can also add directly to the docker-compose file using the 'environment' section. Free wp themes for blog.
Environment Variables
We will define the following environment variables:
- PHP_IDE_CONFIG - This variable defines the server configuration associated with the application. More on this later.
- XDEBUG_CONFIG - This variable allows to define some Xdebug configurations. The 'remote host' is the private ip of your host machine (the one your PHPStorm is running). The 'remote_port' is the port that PHPStorm will be listening for incoming Xdebug connections. These two settings allow PHPStorm and Xdebug to communicate. It wont work without this.
We will add them to our '.env' file like this:
And thats it in terms of code.
Next lets dig into PHPStorm configurations.
PHPStorm configurations
The first thing you should do is to check your Debug settings. In PHPStorm, go to File -> Settings -> Languages and Frameworks -> PHP > Debug.
Make sure you have the some port that you have configured previously in 'XDEBUG_CONFIG' environment variable:
Next, we need to configure a server. This is how PHPStorm will map the file paths in your local system to the ones in your container.
Go to File -> Settings -> Languages and Frameworks -> PHP -> Servers
Give a name to your server. It should match the value you have defined in your 'PHP_IDE_CONFIG' environment variable. We will call it 'symfony-demo'.
The 'host' and 'port' is how will access your application. In my case is localhost:8888.
And then the 'Path mappings'.
In the 'Project files' section you have to map the root path of your application to the path inside the container. In my case its '/var/www/app'.
Click 'Apply' to save your configurations.
The last part is to configure the remote debugger of your project.
On the top right, click on 'edit configurations':
Click in the green 'plus' sign at the top left and select 'PHP Remote Debug' from the list.
Now configure it like this:
Make sure you associate it with the previously created 'server' definition. Use 'PHPSTORM' as idekey.
Your IDE should be now correctly configured. Lets test.
Testing
- Open 'src/Controllers/HelloController.php' and place a breakpoint in the 'hello' method.
- Start your Docker container with
docker-compose up
- Then click on 'Start Listening for PHP Debug connections' icon on top right corner of PHPStorm.
- Open http://localhost:8888?XDEBUG_SESSION_START=PHPSTORM
If everything went well you should see the execution stop at your breakpoint. Windows remote desktop for mac.
And thats it. You should now have a fully configured development environment with Docker and Xdebug integrated with PHPStorm IDE.
If you have any issues or questions feel free to comment bellow or in the GitHub Repository.
Thank you and good debugging ;)
1. Add Xdebug to your PHP application container
Add following lines to your php Dockerfile:
2. Add necessary environment variables
docker-compose.override.yaml
Here we do following things:
- Enable the xdebug extension.
- Enable automatic start on every request (see note on this below).
- Increase default maximal function nesting level, because it is often not enough.
- Instruct XDebug to connect back to the IP where web request came from.
- Instruct XDebug to connect to
host.docker.internal
for command line execution or whenever “connect back” is not possible. - Set
PHP_IDE_CONFIG
env variable toserverName=localhost
. This will tell your PhpStorm which server configuration to use. See next step for details.
3. Configure server in PhpStorm
In your PhpStorm Settings go to
Languages and Frameworks > PHP > Servers
and add a new server:- Name: localhost
- Host/Port: whatever host and port you use to open your local website, for example: ‘magento.localhost’ and ‘8080’.
- Debugger: Xdebug
- Use path mappings: yes
Configure the path mapping according to your source code volume mount in
I have the following mount:
docker-compose.yaml
.I have the following mount:
./magento:/var/www/html
, therefore my local ./magento
directory is mapped to the /var/www/html
path on the server.Debugging
One important thing you need to do is to start listening for PHP debug connections with a small phone icon in your PhpStorm.
Autostart
Normally you would need a browser extension, which adds debug session start flag to your requests when you need it.
However I found it convenient to enable autostart and only control the XDebug via PhpStorm.
The case is that when XDebug tries to start the debugging session but the remote host is not listening, the XDebug does not continue.
So when I don’t need to debug, I just switch listening off. I believe this still adds a small overhead in time for all requests, but for me it is unnoticeable.
However I found it convenient to enable autostart and only control the XDebug via PhpStorm.
The case is that when XDebug tries to start the debugging session but the remote host is not listening, the XDebug does not continue.
So when I don’t need to debug, I just switch listening off. I believe this still adds a small overhead in time for all requests, but for me it is unnoticeable.
If you don’t like this approach, just disable the autostart and start the session your own way (see: Activate debugger).
Creating Run/Debug configurations in PhpStorm
Sometimes it is useful to create and store some specific configuration so you can run it over and over.
I will not describe the whole Run/Debug configurations topic here but only one Docker-specific aspect: you need to teach your PhpStorm to run PHP interpreter inside your container.
I will not describe the whole Run/Debug configurations topic here but only one Docker-specific aspect: you need to teach your PhpStorm to run PHP interpreter inside your container.
For this you need to create a new PHP CLI interpreter configuration:
- in your PhpStorm Settings go to
Languages and Frameworks > PHP
and click the ‘…’ button near the “CLI Interpreter” field. - in new window add a new interpreter “From Docker, Vagrant, VM, Remote…”
- choose “Docker Compose” radiobutton,
- select or create new Server (use Unix socket to connect to Docker daemon)
- choose Docker Compose Configuration files; in my case I choose two in following order:
docker-compose.yaml
docker-compose.override.yaml
- select your PHP app service
- choose “Connect to existing container” instead of starting a new one.
Php Docker Xdebug Phpstorm
This should be enough, save everything and create your Run/Debug configuration using this CLI interpreter.