Debugging php-cli scripts with xdebug and netbeans?

Debugging php-cli scripts with xdebug and netbeans?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Debugging PHP CLI Scripts with Xdebug and NetBeans from the Shell

When you need to debug a complex maintenance script via the command line, launching a session directly from the shell is often more efficient than wrestling with argument parsing in an IDE. While tools like Zend Studio offer documented workflows for this exact scenario, replicating that capability within NetBeans requires understanding how Xdebug intercepts execution and how to bridge the gap between a CLI process and the debugger's transport layer.

The core challenge lies in initiating the debug protocol before your script actually starts running. Unlike web requests where the browser automatically triggers a connection to the Xdebug server, CLI scripts must be explicitly told to halt at a breakpoint or wait for a connection. This is achieved by defining an entry point that Xdebug recognizes as a valid debugging target.

To make this work in NetBeans, you must ensure your project configuration includes the necessary Xdebug extensions and that the debugger is listening on the correct port. Once the IDE is ready, the shell command isn't just about passing arguments; it's about invoking the script with a specific flag or environment variable that signals Xdebug to enter "listen" mode.

In many setups, simply running php script.php arg1 arg2 will bypass the debugger entirely unless Xdebug is configured to auto-start. If your Xdebug configuration (php.ini) does not have xdebug.start_with_request=0 (or if you want explicit control), you need to trigger the debug session manually. The most reliable method involves setting an environment variable or using a specific command-line flag that tells Xdebug to wait for a connection.

For PHP versions prior to 8.2, the standard approach is to set the XDEBUG_CONFIG environment variable or use the -d xdebug.remote_enable=1 directive within a temporary configuration file. However, the most robust technique for CLI scripts is utilizing the xdebug.start_request mechanism via environment variables or specific command-line arguments that mimic a request start.

If you are using Xdebug 3.x, the syntax has shifted slightly towards xdebug.client_host and xdebug.start_with_request. To ensure compatibility across versions without altering your global php.ini, you can prepend the necessary flags directly to your PHP executable:

php -dxdebug.mode=debug script.php arg1 arg2 arg3

This command tells Xdebug to enable debugging mode specifically for this invocation. Once the script hits a breakpoint, it sends a packet back to the debugger client (NetBeans). NetBeans detects this packet and pauses execution at the specified line, displaying the variable states in the Watch window exactly as if you had clicked "Debug" inside the IDE.

If you prefer setting environment variables, which is often cleaner for complex scripts with many parameters, you can export the connection settings before running the command:

export XDEBUG_CONFIG="client_host=127.0.0.1;client_port=9003;remote_enable=1"
php script.php arg1 arg2

A common pitfall developers encounter is forgetting that CLI debugging requires the remote debug port to be accessible to the local machine. Ensure your php.ini or runtime configuration has xdebug.client_host set correctly (usually 127.0.0.1) and xdebug.client_port matching what NetBeans expects (default is 9003).

Another consideration is the entry point of your script. Xdebug needs to know where to stop. If you are using a custom bootstrap file or if your main function isn't wrapped in a way that allows breakpoint insertion, ensure that xdebug.start_with_request is not set to 1 globally if you want conditional debugging. Instead, rely on the explicit start request triggered by the environment variable or the command-line flag mentioned earlier.

For those managing large maintenance scripts where argument passing from NetBeans becomes unwieldy, this CLI-driven approach offers a significant workflow improvement. It allows you to prepare the full list of arguments in your shell history or script file and then simply attach the debugger when needed. This hybrid approach combines the power of command-line flexibility with the introspection capabilities of a modern IDE like NetBeans, giving you the best of both worlds without needing to refactor your argument handling logic into an HTTP request or a dedicated web entry point.

If you require further assistance setting up complex debugging environments or need support for specific Laravel-related CLI tools, resources like LaravelCompany can provide additional context on modern PHP development practices.

Our network