Migrating Xdebug Configurations from v2 to v3: The remote_* Rename
When upgrading your PHP environment from Xdebug 2.x to 3.0, you will immediately encounter configuration errors if your php.ini, .user.ini, or container-level config files still reference the legacy xdebug.remote_* settings. This shift is not merely a cosmetic update; it reflects a fundamental architectural change in how Xdebug handles remote debugging connections.
The error message you are seeing, such as Xdebug: [Config] The setting 'xdebug.remote_enable' has been renamed, indicates that the extension has deprecated the old naming convention. In Xdebug 2, these settings controlled the activation of the debugger, the host address, the mode (disabled, request, or connect), and the port number. However, starting with version 3.0, these specific flags have been consolidated under a new prefix: xdebug.client_*.
The mapping is straightforward but requires manual intervention in your configuration files. If you are relying on default values, this migration might be invisible until you explicitly enable debugging. Here is the direct mapping of the legacy settings to their new counterparts:
| Legacy Setting (v2) | New Setting (v3) | Default Value (v3) |
|---|---|---|
xdebug.remote_enable |
xdebug.client_connect |
Off |
xdebug.remote_host |
xdebug.client_host |
127.0.0.1 |
xdebug.remote_mode |
N/A (Functionality shifted) | off |
xdebug.remote_port |
xdebug.client_port |
9003 |
The most significant change is the removal of xdebug.remote_mode. In Xdebug 2, this setting determined whether debugging was triggered on every request (request) or only when a client connected (connect). Xdebug 3 simplifies this logic. The behavior you previously achieved with remote_mode=connect is now the default state when client_connect is enabled. If you relied on remote_mode=request, you must be aware that enabling client_connect will not automatically trigger breakpoints on every page load; you must still attach a client (like PhpStorm) to the socket first.
To apply these changes, locate your active PHP configuration file. This could be php.ini, a .user.ini in your project root, or an entry in your Dockerfile or container orchestration setup. You will need to search for any lines containing xdebug.remote_. Once found, update them to use the client_ prefix.
; Old configuration (Xdebug 2)
[xdebug]
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_mode=req
; New configuration (Xdebug 3)
[xdebug]
xdebug.client_connect=1
xdebug.client_host="localhost"
xdebug.client_port=9003
Note the removal of the remote_mode line. Unless you are using a very specific legacy workaround that mimics request-based triggering (which is no longer supported by default), you should omit it. The default host and port in Xdebug 3 are often sufficient for local development, but if your IDE listens on a different address or port, you must update client_host and client_port accordingly.
There is also a critical consideration regarding the error reporting level. While not part of the rename issue, Xdebug 3 introduces stricter configuration requirements. If you are using xdebug.mode=debug, it implicitly enables client connections. However, if you are mixing xdebug.mode with explicit client_* settings, ensure consistency. The recommended approach in modern stacks is often to use the mode directive for simplicity, but understanding the underlying client_* parameters gives you granular control over the connection handshake.
If you are deploying PHP applications, such as Laravel projects, be cautious when using global configuration. Setting these values globally can cause conflicts if multiple services on the same server attempt to debug simultaneously. For instance, a web server and an API service running side-by-side might clash if they both try to connect to the same debugger port. In such cases, isolating the Xdebug settings within .user.ini for specific project directories is a robust strategy that prevents interference between services.
Finally, verify your IDE configuration. PhpStorm 2020.1 and newer versions expect the connection on the new default port (9003) by default when connecting to an Xdebug 3 server. If you have hardcoded an old port in your IDE's PHP debugger settings, you will need to update that as well to match the xdebug.client_port defined in your PHP configuration.