Troubles with setting up Grav, Xdebug and PhpStorm

First of all, I know this is a lengthy post because I tried to give a complete overview of what I did with as much detail as possible.

Over the years I have created a couple of Grav plugins. The process of creating and figuring out how Grav works was rewarding but often frustrating as well. Last week I decided to make life easier by purchasing PhpStorm. I was really looking forward to inspecting variables when a fatal error 500 occurs. And they do quite frequently since I’m not a developer by far.

To my disappointment I can’t make it all work. To me the “zero config” setup of PhpStorm with Xdebug as shown in the Grav blog post Grav + PHPStorm + Xdebug Video is not as zero as I would like it to be.
Below is a reconstruction of what I tried.

On a Windows 10 machine I’m using Grav’s built-in webserver starting it with:
php bin/grav server. For anyone unfamiliar with this feature, see Using Grav’s new built-in Web Server.

The server uses PHP version 7.4 which is installed in “C:\Users\Medewerker\php7”. There is no other webserver or PHP version installed on this machine.

Grav including the Admin Plugin runs excellent.

As instructed by the Xdebug installation wizard I added this line to my php.ini file:
zend_extension = ext\php_xdebug-3.0.4-7.4-vc15-nts-x86_64.dll

Then php --version shows:

PHP Warning:  Failed loading Zend extension 'ext\php_xdebug-3.0.4-7.4-vc15-nts-x86_64.dll'
(tried: ext\ext\php_xdebug-3.0.4-7.4-vc15-nts-x86_64.dll (Kan opgegeven module niet vinden.), ext\php_ext\php_xdebug-3.0.4-7.4-vc15-nts-x86_64.dll.dll (Kan opgegeven module niet vinden.)) in Unknown on line 0

BTW “Kan opgegeven module niet vinden” means “Can’t find the specified module”.

Though “C:\Users\Medewerker\php7” is in my PATH variable (I checked with $Env:Path) PHP can’t find the Xdebug DLL in the ext directory.

PHP does find the extension when I prepend the path of the ext directory so the entry becomes:
zend_extension = C:\Users\Medewerker\php7\ext\php_xdebug-3.0.4-7.4-vc15-nts-x86_64.dll

After this change a php --version now shows:

PHP 7.4.16 (cli) (built: Mar  2 2021 14:06:13) ( NTS Visual C++ 2017 x64 )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethans

A restart of the built-in webserver shows (shortened a bit):

The Web server is using PHP CGI 7.4.16

[Web Server ] Apr 25 10:38:42 |DEBUG  | PHP    Reloading PHP versions
[Web Server ] Apr 25 10:38:42 |DEBUG  | PHP    Using PHP version 7.4.16 (from default version in $PATH)
[Web Server ] Apr 25 10:38:42 |INFO   | PHP    listening path="C:\\Users\\Medewerker\\php7\\php-cgi.exe" php="7.4.16" port=59667

At this point I also have the Xdebug helper extension for Chrome installed. I can enable it and then it shows it’s bug icon in green in the browser.

As a next step I follow the PhpStorm documentation Configure Xdebug.

Using the settings for Xdebug 3 I added these line to the php.ini file:
xdebug.mode = debug
xdebug.client_host =
xdebug.client_port = 9003

After changing the ini file I restarted the webserver.

Again inspecting the output of phpinfo() in the browser I see a section named “xdebug” which shows among many other settings:

What I think is strange is that though the Xdebug version shown in the output is “3.0.4” it seems like PHP or Xdebug uses version 2 settings. There are many lines like these:
“xdebug.auto_trace (setting renamed in Xdebug 3)”

Then the configuration of PhpStorm starts by doing Ctrl-Alt-S to show the PhpStorm settings. In the PHP section it shows the correct PHP version (7.4.16) and at “Debugger” it states: “Xdebug 3.0.4”. Also it reports the correct (and only) php.ini file (“C:\Users\Medewerker\php7\php.ini”).

At this point the configuration moves into the Debug section in the PHP configuration section. This is where it gets a bit complicated for me.
If I remember correctly all these options where checked by default at my first encounter with PhpStorm (out of the box):

  • Resolve breakpoint if it’s not available on the current line (Xdebug 2.8+)
  • Force break at first line when no path mapping specified
  • Force break at first line when a script is outside the project

I did try with some and all of these options unchecked with no desired results. So I have them all checked at this moment.

The Xdebug Debug port is set to 9003, the same as in the php.ini file.

At this point and onwards I get totally lost in the documentation and settings. For instance, I don’t understand the consequences of the “Force break at first line …” options. To me it says “Whenever a PHP script is called PhpStorm stops at the start of the script” and then I think why is that useful at all?

The setup seems OK if I look at the results of the Web Server Debug Validation check. The result is shown in the attached image.

PhpStorm is listening and reports an incoming connection upon a browser page refresh. But then is writes “Debug session was finished without being paused” to it’s Event Log panel. This makes sense to me: I refreshed the Grav Admin Dashboard page and it runs fine. No errors in there so PhpStorm doesn’t need to stop or pause.

The problem is that the same behaviour occurs when I refresh a page which calls a plugin with an uncaught fatal error.

The Event Log suggests to have a look at the PHP|Servers settings. There it shows PhpStorm creates another server with every page refresh. The name (“localhost:8000”) gets a sequence number appended like “localhost:8000 (2)”. The Host is set to “localhost:8000” with Port “8000” (and Debugger “Xdebug”).
I then remove the extra Server entries and set the Host back to “localhost” without the port number because somewhere I did see logging of “localhost:8000:8000/” which can’t be good.

All I want is having PhPstorm catch unexpected errors, point me to it and let me examine the variables at that point in the code. I’m sure it can be done, I just can’t figure out how to make it work.

I really hope someone read all this all the way down here and knows what is wrong. Any help is greatly appreciated!

I’ll be honest - I didn’t read your long post, but I can share a solution that works on my machine :smiley:

I’ve searched a lot for this myself, but couldn’t find a step by step guide, so had to combine multiple solutions until it worked. Windows 10 + Laragon + PHPStorm + Chrome

Comment out in php.ini original zend_extension line Then add this:

xdebug.remote_enable = 1
xdebug.idekey = PHPSTORM

OC change path to your Xdebug. In Chrome Xdebug helper select PHP Storm. Setup Xdebuger as described here (except the parts you already have and I didn’t add client host or port)

In PStorm I have this:

When you first run a request, PStorm will ask for some path IIRC. You have to choose your initial script on a correct project if you have multiple

Hi @bleutzinn ,
just like @Karmalakas , I can’t give any direct advice for your specific setup, but share my own experience using an IDE + Grav + Xdebug for local Grav Plugin Development.
I am using VS Code as IDE, and a local docker Instance on my development machine - the Problem here was to figure out how to get this all to work together.
I ended up modifieing the official Grav Docker Image to include Xdebug and fiddle with the setup to get it to work with my IDE.
The modified Docker repo is at my GitHub Page which also includes a Link to some Docs.
The whole thing is not yet finished and will be improved further, but, at least, ATM, it works for me.
Maybe this can also be of some use here.

@Karmalakas @hoernerfranz thanks for your suggestions. And it’s good to share your setups here for others to try also.

Maybe I didn’t explain that Xdebug and PhpStorm are working fine with normal debugging by manually setting breakpoints in the code.

But what I want is that PhpStorm is called via Xdebug when an unexpected and unhandled error occurs and sets the cursor at the line after the line with the error.

This is exactly as described in the JetBrains blog article Just-In-Time debugging and PHP Exception Breakpoints with PhpStorm and Xdebug. Unfortunately that is from 2013 and of course things have changed since then.

This article Debug with a PHP web page debug configuration in the latest PhpStorm documentation (for version 2021.1) has some really promising configuration options but still execution does not stop at the error.

I’m not good in configuring everything, but from what I read, this break on error mode is pretty much useless (or do you have some use cases?)

I mean to use debugger normally you constantly have to edit php.ini by switching between req and jit

Note that when jit debugging is enabled in php.ini , traditional debugging options using HTTP GET/POST variables will not work. For that, Xdebug’s remote_mode setting has to be reverted to “ req ”.

And if there’s an error you’d still notice it and see where the error is and you can add a breakpoint on the line which fails. I really don’t see a point of JIT debugging :thinking:

Maybe I’m missing something?

Visual Studio Code shows by default the default breakpoints ‘Notices’, ‘Warnings’, ‘Errors’, 'Exceptions` and ‘Everything’.

When I tick ‘Exceptions’ and I throw an Exception in my code, it sure breaks at the correct line… No fiddling with php.ini…

Do I use it? No never… Getting notified in the browser about the Exception gets me triggered.

And ticking ‘Everything’ will certainly give you a headache.

@Karmalakas and @pamtbaau, thanks for stepping in.

Maybe there is some misunderstanding here between developers and someone who is not and tries to get something working in Grav. The latter being me obviously.

My expectations I think come from using the Borland Delphi IDE years ago. If something breaks the IDE takes you to it. Simple as that.

Of course I can see the PHP code line number with an error or look it up in Grav’s log file. But if I can surely PhpStorm can do that too. Then why decide not to?

My use case starts with an Ajax call which lets PHP read a custom YAML config file, process it and which results in a modal form being returned so it gets shown via Javascript. This is why in this use case I don’t get notified in the browser by Grav’s standard Error Display page.

As said I expected to be taken to the erroneous line but it seems I set my expectations too high.

@bleutzinn, Ah… you’re right. When using Ajax you won’t get notified in the browser.

Currently I’m using VScode on Windows 10 + WSL2 (Ubuntu 20.04) and coding and debugging works fine for me as said above.

Since I’m quite impressed with Android Studio (Intelij based) and PyCharm, I decided to download the trial version of the WebStorm beast.

XDebug was already working properly on my system, so what could possibly go wrong?

Well… I’ll spare you the details… I couldn’t get it to work and my self-esteem is out of the window…

Thanks for trying. I’m sure your self-esteem will be back soon. :grinning:

Let’s hope someone gets it working and posts a how-to in here.

Yes, AJAX debugging is always a PITA :frowning: Maybe I’ll try to look into JIT some day, but not any time soon. For now, if I notice something is not working as expected on AJAX calls, I just Replay XHR request in Dev tools :thinking: