Debugging ISLE-ld (Local Development) in PHPStorm
Debugging ISLE on a Mac
This guidance applies to debugging PHP code in a local
ISLE-ld, that’s http://isle.localdomain, instance using PHPStorm.
Before engaging PHPStorm we need to make one change to our
ISLE-ld configuration by running a
docker cp command, making a change to our
docker-compose.override.yml file, and restarting the stack. Here are the commands and procedure.
mkdir -p persistent/html
docker cp isle-apache-ld:/var/www/html/. ./persistent/html
The above commands will make a new
./persistent/html directory on the host, if one does not already exist, and the
docker cp command will copy the current contents of the Apache container’s
/var/www/html directory to the host. Next we need to modify
docker-compose.override.yml to map the
./persistent/html directory into the container.
On the host, open
docker-compose.override.yml in your favorite editor and remove comments from the three lines that read:
- ./persistent/html:/var/www/html # necessary for PHPStorm debugging!
|Proper indentation in |
Having saved the modified
docker-compose.override.yml file, restart things by doing the following.
docker-compose up -d
In a minute or two your
http://isle.localdomain should be back up and running, and ready for debugging in PHPStorm.
In the PHPStorm menu go to:
Preferences > Languages & Frameworks > PHP > Debug > DBGp Proxy and set the following settings:
IDE key: `PHPSTORM` Host: `docker.for.mac.localhost` Port: `9009`
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.
The following is a ONE TIME procedure. If you’ve already done this then all you need to do is select the PHPStorm project, one you created and named earlier, from the PHPStorm splash screen.
- From the PHPStorm splash screen choose
Create New Project from Existing Files. Click
- CRITICAL…pay attention to this! Select
Source files are in a local directory, no Web server is yet configured.. Click
- A directory map of your host should appear. Navigate in this map to your ISLE project, the folder where your
docker-compose.ymlfile exists. There should also be a
./persistent/htmlfolder there from steps we took in the previous section. Choose the
Project Root, then click
- You now have a new “local” project named
- Relax a little while your PHPStorm project is indexed for the first time.
Launching a Web Debug Session
Once you’re all setup and have your PHPStorm project open…
- Set breakpoints in your code, toggle
Start listening for PHP connectionson (the green/red telephone icon). When turned on the red parts of the icon turn green.
- Open the
Runmenu in PHPStorm and look near the bottom of the window for the
Break at first line in PHP scriptsoption. Ensure that it is toggled
ONso that your debug session will encouter at least one breakpoint.
- Now open your browser and navigate to your site (mine is
- In PHPStorm you may see a pop-up window titled
Incoming Connection from XDebug. Click
- If everything is working properly your PHPStorm
Debugwindow pane will open and if you click the
Debuggertab you’ll see your
index.phpcode and a cursor with the first line of code highlighted, usually:
Debugging CLI (aka Drush) Commands
Visit the PHPStorm menu
Preferences > Languages & Frameworks > PHP > Servers and add a server named
Docker with the following parameters:
- Use path mappings:
- Absolute path on server:
Open a terminal into the
isle-apache-ld container and run
export PHP_IDE_CONFIG=serverName=Docker to complete the configuration.
Set breakpoints in your Drush code and run any
drush command in the same
isle-apache-ld terminal with debug listening toggled on in PHPStorm.
And that’s a wrap. Until next time…