How to get XDEBUG to work with VSCODE when you're using php 7.x?

Local Add-ons Xdebug + VS Code
1

What is the problem?

Local’s XDEBUG configuration is using the syntax compatible with XDEBUG version 3.x. Because there is no compatible XDEBUG version 3.x for PHP version 7.4.3 (yet), XDEBUG version 2.x is deployed. However, XDEBUG version 2.x does not support the new XDEBUG version 3.x syntax in php.ini and thus sticks to the XDEBUG configuration defaults.

Does this problem apply to you too?
To save you some time, please check if the following information also applies to you. Most importantly, the output of phpinfo() should show that your deployment is using XDEBUG version 2.x

Local version: 6.6.1-6281

Output of phpinfo() shows:

This program makes use of the Zend Scripting Language Engine:
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.3, Copyright (c), by Zend Technologies
    with Xdebug v2.9.0, Copyright (c) 2002-2019, by Derick Rethans

How do you solve this problem?
In order to generate a php.ini file for a particular deployment, local uses template files with the hbs file extension. There are two levels of template files:

  • System level, which is used as a template to generate a deployment level template. For example, %AppData%\Roaming\Local\lightning-services\php-7.4.30+5\conf\php.ini.hbs
  • Deployment level, which is used as a template to generate a deployment level php.ini file every time you start your deployment. For example, <YourDeploymentDirectory>\conf\php\php.ini.hbs

The problem as stated is that the templates contain a syntax which is compatible with XDEBUG version 3:

[xdebug]
zend_extension = php_xdebug.dll

xdebug.mode=debug,develop; INCOMPATIBLE
xdebug.client_port=9003; INCOMPATIBLE
xdebug.discover_client_host=yes; INCOMPATIBLE
xdebug.start_with_request=yes; INCOMPATIBLE

As you can see, most directives are not understood by XDEBUG version 2 and hence the default settings apply like port 9000 and critical settings, required to get XDEBUG to connect to the debugger in VSCODE, are missing.

For XDEBUG 2.x, the following configuration in php.ini will ensure that XDEBUG connects to the debugger listening on TCP port 9000 every time PHP executes code.

[xdebug]
zend_extension = php_xdebug.dll

xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000

In order to have these settings in your deployment’s php.ini file, it is imperative that you edit the corresponding deployment level php.ini.hbs file <YourDeploymentDirectory>\conf\php\php.ini.hbs:

{{#if xdebugEnabled}}
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
{{else}}
xdebug.remote_autostart=0  
xdebug.remote_enable=0
xdebug.profiler_enable=0
{{/if}}

[localbyflywheel]
xdebug.scream = 1
xdebug.show_local_vars = 1
xdebug.idekey = VSCODE

IMPORTANT: Stop and start your deployment to have the changes take effect. If you feel so inclined, you can validate that your deployment’s php.ini has been updated accordingly. (File: %AppData%\Roaming\Local\run\<LocalDeploymentID>\conf\php\php.ini)

As alluded to before, this will fix your current deployment’s XDEBUG configuration. Also edit your system level template file for any new PHP 7.4 instances you might want to deploy: %AppData%\Roaming\Local\lightning-services\php-7.4.30+5\conf\php.ini.hbs

This fixes the server side. In VSCODE you now need to create launch profiles for which I’ve used Local’s XDEBUG + VS Code add-on. It’s important to understand what Local has done because it’s not obvious unless you’re very well aware of XDEBUG developments. Basically, if you use the add-on, 3 launch profiles are created:

  • Listen for Xdebug 3.0 (Local) (public): This is for XDEBUG 3.x for which NO compatible version for php 7 exists.
  • Listen for Xdebug (Local) (public): This is for XDEBUG 2.x which is compatible with PHP version 7.4.3 currently used in Local.
  • Launch currently open script

So, in order to get XDEBUG to work with the php configuration for your instance, you will need to choose “Listen for Xdebug (Local) (public)” to have your IDE listen on port 9000 for connections of XDEBUG.

The launch configurations look like this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug 3.0 (Local)",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "xdebugSettings": {
                "max_children": 128,
                "max_data": 1024,
                "max_depth": 3,
                "show_hidden": 1
            }
        },
        {
            "name": "Listen for Xdebug (Local)",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "xdebugSettings": {
                "max_children": 128,
                "max_data": 1024,
                "max_depth": 3,
                "show_hidden": 1
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000,
            "xdebugSettings": {
                "max_children": 128,
                "max_data": 1024,
                "max_depth": 3,
                "show_hidden": 1
            }
        }
    ]
}

I hopes this clarifies matters and hope to see this resolved in a future version of Local.

1 Like