Xdebug Handler Laravel Package

Getting Started

Add the package via composer require composer/xdebug-handler. Then, in your CLI application’s entry point (e.g., bin/myapp), instantiate and invoke the handler early—before any heavy initialization:

#!/usr/bin/env php
<?php

require __DIR__ . '/vendor/autoload.php';

use Composer\XdebugHandler\XdebugHandler;

$xdebug = new XdebugHandler('myapp');
$xdebug->check();
unset($xdebug);

// ... rest of app logic

This is the minimal setup. It automatically detects if Xdebug is loaded and not in xdebug.mode=off, and restarts the process without Xdebug—unless MYAPP_ALLOW_XDEBUG=1 is set. Start here if you want to avoid Xdebug’s performance penalty in long-running CLI tools (e.g., build scripts, workers, or PSR-15 console apps).

Implementation Patterns

• Simple CLI tools: Use the basic pattern above. Wrap check() at the top of your main script; no extra configuration needed.
• Subprocess management: When spawning other PHP processes (e.g., via symfony/process or proc_open), use Composer\XdebugHandler\PhpConfig to ensure Xdebug is excluded unless explicitly needed:

  $config = new PhpConfig();
  $options = $config->useStandard(); // Add [-n, -c, tmpIni] to command
  $process = new Process(['php', ...$options, 'script.php'], ...);
  

• Custom restart logic: Extend XdebugHandler and override requiresRestart() and/or restart() to control when a restart happens (e.g., skip on --help, or inject additional ini overrides for phar.readonly).
• Logger integration: Pair setLogger() with PSR-3 to surface restart status in logs—crucial for debugging in CI or production environments.
• Portable ini access: Replace raw php_ini_loaded_file() calls with XdebugHandler::getAllIniFiles() in restarted contexts to avoid reporting incorrect paths.

Gotchas and Tips

• CLI-only: This is for CLI only. It silently does nothing on FPM/Apache modules.
• -n vs -c nuance: Standard restart uses -n (skip scan dir) + -c (temp ini). Persistent mode sets PHPRC/PHP_INI_SCAN_DIR environment variables—this affects all subprocesses, not just the immediate restart. Choose carefully based on subprocess hygiene needs.
• xdebug.mode=off bypass: If Xdebug is loaded but xdebug.mode=off, no restart occurs. You’ll see a debug log like No restart ... Allowed by xdebug.mode.
• Debugging failures: Set XDEBUG_HANDLER_DEBUG=2 to see where the temp ini is written and whether creation succeeded. Common failure: open_basedir or sys_temp_dir restrictions preventing temp file creation.
• MYAPP_ORIGINAL_INIS is a path-separated string: When using getRestartSettings()['inis'], the first entry is php_ini_loaded_file(), the rest are from php_ini_scanned_files().
• Subprocess Xdebug leakage: If you spawn subprocesses without using PhpConfig, Xdebug will reappear unless they also call xdebug-handler. This is the #1 gotcha—always pass useStandard() or usePersistent() options into subprocess calls.
• Phar readiness: Your phar must be writable if you override restart() to inject ini settings (e.g., phar.readonly=0). Consider copying into a temp dir first if packaging signed phars.
• Signal handling: PCNTL is auto-handled, but on Windows ≥7.4, only the restarted process responds to CTRL+C—the parent ignores it. Don’t rely on parent-process cleanup for interactive signals.