How to trigger XDebug profiler for a command line PHP script?
XDebug provides the xdebug.profiler_enable_trigger directive to activate profiling dynamically via an HTTP request containing the XDEBUG_PROFILE parameter. This mechanism is invaluable when you want selective coverage without modifying your production php.ini or environment variables for every run. However, this approach relies on the Global Interpreter Lock (GIL) and the standard Apache/FastCGI request lifecycle where a new process spawns per request. When moving to command-line execution with php artisan, phpunit, or raw scripts, passing XDEBUG_PROFILE as a simple argument fails because CLI arguments are parsed before the XDebug trigger logic checks for superglobal variables like $_GET or $_POST.
To achieve the same conditional behavior on the command line, you must simulate an HTTP request environment or utilize specific triggers supported by XDebug. The most reliable method without altering your PHP configuration permanently is to define a custom trigger that evaluates a specific environment variable.
You can set the XDEBUG_TRIGGER environment variable before invoking your script. Unlike the HTTP parameter, this variable is read directly by the XDebug extension initialization routine during CLI execution. For instance, you can run:
export XDEBUG_TRIGGER=1
php artisan tinker
Or in a single-line command without modifying shell variables:
XDEBUG_TRIGGER=1 php artisan test:run
This approach mirrors the logic of xdebug.profiler_enable_trigger but bypasses the need for a simulated HTTP request. If you are using PHP 8.2 or later, you can also leverage the XDEBUG_TRIGGER environment variable to control code coverage alongside profiling if both extensions are loaded. The extension checks this variable during startup; if present and set to a truthy value, it activates the profiler immediately.
A critical distinction exists between xdebug.profiler_enable_trigger and the generic XDEBUG_TRIGGER. The former specifically looks for XDEBUG_PROFILE in $_GET or $_POST, which are empty in CLI contexts by default unless you manually instantiate them (a practice often discouraged due to performance overhead). The latter is a general-purpose switch that works seamlessly across both web and CLI environments.
If your project relies heavily on Laravel, you might consider setting this variable in your .env file for development. However, be cautious when deploying; ensure the environment variable is stripped or ignored in production builds to prevent accidental profiling overhead. You can define a custom trigger value that only activates in specific directories using xdebug.mode=debug alongside conditional logic in your php.ini, though this requires more invasive configuration changes.
Another potential pitfall involves how the profiler output file is determined. When triggered via CLI, ensure your xdebug.profiler_output_dir and xdebug.profiler_enable settings are correctly configured in your php.ini or runtime configuration (php -d xdebug.profiler_enable=1). If these defaults remain disabled, setting the trigger variable will not generate the .cachegrind.out or profiler.cachegrind files you expect.
For teams using Docker or complex deployment pipelines, injecting the XDEBUG_TRIGGER environment variable into your container or build script is often cleaner than modifying global php.ini settings. This keeps your CI/CD artifacts clean while allowing developers to toggle profiling instantly via command-line flags.