Configuring PhpStorm

Last updated on

9 August 2023

This Article explains to you how to configure your PhpStorm to work with your local installation of Drupal and debug using XDebug. If you would like to know how to install Drupal or Acquia Drupal or XDebug please refer to the many articles already published.

For full documentation on using PhpStorm and Drupal, refer to the JetBrains documentation.

Installing PhpStorm

Download trial PhpStorm https://www.jetbrains.com/phpstorm/
Install...

Enable Drupal support

PhpStorm has built-in support for things like autocompletion, syntax highlighting, Drush, integration with the Drupal.org issue queue, and more. Read about how to enable and configure it in the official PhpStorm documentation.

PhpStorm and Xdebug in DDEV or Lando

With these steps you can get PhpStorm and Xdebug working together in DDEV or Lando. There are many moving parts, and it can be challenging to make it work, so the point here is simply to get it running, with the fewest steps. There are many tutorials which can help you further with the debugging.

An existing Drupal 10 installation made with Composer (web root in /web folder) running in DDEV or Lando is assumed.

DDEV setup

Setting up Xdebug in DDEV is extremely easy. Open PhpStorm and then:

Install the DDEV Integration Plugin via Preferences → Plugins → Marketplace
Enable "Use Compose V2" under Build, Execution, Deployment → Docker → Tools
Restart DDEV and start Xdebug by running ddev xdebug

Note: You may need to open port 9003 in your firewall.

Lando setup

Note: Remember to run lando rebuild to enable Xdebug in an existing Lando instance.

A basic .lando.yml could look like this. Enable the XDEBUG_SESSION_START line, if you want to start a Xdebug session every time Lando starts.

name: drupal10
recipe: drupal10
config:
  webroot: web

services:
  appserver:
    xdebug: develop,debug
    overrides:
      environment:
        # Support debugging CLI with XDEBUG.
        PHP_IDE_CONFIG: "serverName=appserver"
        # XDEBUG_SESSION_START: lando

Open the front page of the web site, and send a signal to Xdebug and PhpStorm to initiate debugging by appending ?XDEBUG_SESSION_START=lando to the URL, like this. Alternatively, use cookie method:
https://drupal10.lndo.site?XDEBUG_SESSION_START=lando

As an alternative to initiate debugging by appending ?XDEBUG_SESSION_START=lando you can create a cookie manually. First time PhpStorm/Xdebug receives the parameter, a cookie is set in the browser, and further reloads will stop at any break-point, even without the XDEBUG_SESSION_START parameter present. You can create this cookie yourself:

Open Firefox Console with Ctrl + Shift + K, in Chrome use Control + Shift + J
Paste in the expression below, and press Ctrl + Enter to set the cookie:
document.cookie = "XDEBUG_SESSION=lando";

Check under Storage > Cookies if it worked. You can remove the cookie by running this in the Console:
document.cookie = "XDEBUG_SESSION=; expires=Thu, 01 Jan 1970 00:00:00 UTC;";

Add Xdebug breakpoint in PhpStorm

Open PhpStorm
Open the Drupal installation
Open index.php
Place a break-point at line 16, clicking right of the number in the gutter, which should create a red dot:
Click the icon with the little green bug and phone hook ("Start Listening for PHP Debugging Connections") in the upper right corner:
The icon should change, and the red sign change, to indicate it's in listening mode:
If everything worked as expected, PhpStorm pops up. First time it is triggered, an "Incoming Connection from Xdebug" prompt opens with some default settings. Usually you can just click "Accept", and continue. You can adjust later, if needed.
If all went well, PhpStorm should now be showing the available variables at line 16 of index.php file. Congratulations, you can now debug Drupal code, step-by-step!

Creating a project

It is assumed you already have a full Drupal environment which includes: Apache, MySQL, PHP, Drupal and XDebug
So, as a result, we have two assumptions:

your local Drupal site is at http://mylocalsite (usually it's http://localhost);
your local Drupal code is at c:\path\to\my\local\code
which is also the DocumentRoot for mylocalsite vhost config in Apache.

So here is what you need to do:

File --> New Project from Existing Files
choose Web Server is installed locally, source files are located under its document root --> Next
enter the path of your local Drupal code c:\path\to\my\local\code
Local Server:
- Name: your project name should be fine
- Web server root URL: should be http://mylocalsite:[port]
- Web path for project root: leave blank. In Drupal projects, the web path is the same as the path to the source code --> Finish

Setting up a server

So it should look something like this:

That's it!

Now place some breakpoints and click on Debug (Shift + F9)

Run --> Edit Configurations
click on the yellow plus button --> PHP Web Application
Name: your project's name
Server:
1. click on the button
2. Name: your server name (any name)
3. Host: mylocalsite (without the http://)
4. Port: your mylocalsite port
5. Debugger: Xdebug
6. click OK
in Server choose the server you just created
Browser: your favorite browser where the site will be open
Click OK

Configuring PhpStorm to link to Drupal.org's GitLab

You can create an "external tool" that will allow you to select code, and have a link to git.drupalcode.org of that code put on your pasteboard for sharing with other people so they can look at what you are looking at.

Start by making a script called "pasteboard" - put it in /usr/local/bin.
Then go to preferences => tools => external tools and add one with the fields you see in this screenshot.

If the project name does not match then you can hard code it like http://git.drupalcode.org/project/drupal/blob/$Prompt$/$FileRelativePath$#L$SelectionStartLine$-$SelectionEndLine$
Then, once its saved you should be able to highlight any code, right click, and go through the 'external tools' menu like so:
It will pop up with a dialog that just says 'enter parameters' : this is where you type in a branch name for whatever branch you're on.
As soon as you do, your clipboard should have the url directly to the code you highlighted, on your pasteboard, with the intent of sharing it with somebody: http://git.drupalcode.org/project/drupal/blob/8.9.x/core/lib/Drupal/Core/Utility/ProjectInfo.php#L42-74
You can then assign it a keyboard shortcut too so you can just highlight cmd-shft-something and type the branch and paste

Debugging Xdebug

Sometimes you need to debug Xdebug, and one method is adding this in a page, which will print out the values of Xdebug’s diagnostic log on the screen:

xdebug_info();
exit;

For more debug tips, see Setup Step Debugging in PHP with Xdebug 3 and Docker Compose.

Free license for Drupal contributors

JetBrains supports non-commercial open source projects, and Drupal contributors with 35 or more issue credits gained over the past year can get a free PhpStorm license. See also Free PhpStorm licenses for Drupal contributors.