README

PHP Debug Pilot 🚀

Zero-Configuration PHP Debugging Setup.

PHP Debug Pilot is an enterprise-grade CLI tool that automatically detects your environment, installs and configures Xdebug, and generates ready-to-use launch configurations for your favorite IDE. Stop wrestling with php.ini and port mappings — just fly.

✨ Features

🔍 Environment Detection — Automatically detects OS (macOS, Linux, Windows), Docker containers, and php.ini location
⚙️ Smart Configuration
- Configures Xdebug for step debugging (mode debug, auto-client-host)
- Idempotent — runs safely multiple times without duplicating config blocks
📦 Extension Management
- Check Status — View installed/enabled status of Xdebug at a glance
- Toggle — Enable or disable extensions with a single command
- Auto-Install — Detects missing extensions and offers to install them for you (macOS/Linux)
💻 IDE Integration — Generates project-specific config files for:
- VS Code (.vscode/launch.json)
- Sublime Text (*.sublime-project)
- Planned editors (contributions welcome!):
  - PhpStorm
  - Vim / Neovim
  - Zed
  - Athas
🏥 Health Checks — Verifies your installation and reports actionable warnings (e.g., missing extensions, wrong modes)

📦 Installation

Requirements

PHP ^8.2
Composer (for Method 2 & 3 only)

Method 1: Standalone PHAR (Zero Dependencies)

This is the best method if you don't want to manage global Composer dependencies or prefer a single executable file.

Download and install the standalone PHAR:

curl -sLO https://github.com/Gemui/php-debug-pilot/releases/latest/download/debug-pilot
chmod +x debug-pilot
sudo mv debug-pilot /usr/local/bin/debug-pilot

Verify the installation:

debug-pilot --version

Method 2: Via Composer (Global)

Install once and use debug-pilot from anywhere:

composer global require gemui/php-debug-pilot

⚠️ Important: Ensure your global Composer binaries directory is in your system's $PATH.

Typically this is ~/.composer/vendor/bin or ~/.config/composer/vendor/bin.

Add it to your shell profile if you haven't already:
export PATH="$HOME/.composer/vendor/bin:$PATH"

After installing globally, you can use debug-pilot directly:

debug-pilot              # Interactive setup wizard
debug-pilot status       # Extension status table
debug-pilot toggle xdebug

Method 3: Per-Project Installation

Add it as a dev dependency to a specific project:

composer require --dev gemui/php-debug-pilot

Then use it via Composer's local bin:

./vendor/bin/debug-pilot

🔄 Updating

Method 1: PHAR

The PHAR binary includes a built-in self-update command that downloads the latest release from GitHub:

debug-pilot self-update

Method 2: Global Composer

composer global update gemui/php-debug-pilot

Method 3: Per-Project

composer update gemui/php-debug-pilot

🚀 Usage

Interactive Setup

Run the setup wizard to configure extensions and generate IDE files:

debug-pilot

The tool will:

🔍 Detect your environment
🐛 Ask which debugger you want to configure (Xdebug)
💻 Ask which IDE you use
✅ Write the configuration and verify the setup

Check Status

See which extensions are installed and enabled:

debug-pilot status

Output:

 ┌─────────┬───────────┬─────────┐
 │ Driver  │ Installed │ Enabled │
 ├─────────┼───────────┼─────────┤
 │ xdebug  │ ✅        │ ✅      │
 └─────────┴───────────┴─────────┘

Enable / Disable Extensions

Toggle extension state without editing php.ini manually:

# Enable Xdebug
debug-pilot toggle xdebug

💡 Tip: If the extension is not installed, the tool will offer to install it for you automatically (on supported systems).

Install Extensions

Manually install a specific extension:

# Install Xdebug
debug-pilot install xdebug

🔧 The tool will automatically detect if auto-installation is supported on your system and run the appropriate installation command. If auto-installation is not available (e.g., Docker, Windows), it will display manual installation instructions.

Non-Interactive Setup

Perfect for CI/CD pipelines or automated setup scripts:

# Configure Xdebug for VS Code
debug-pilot setup --debugger=xdebug --ide=vscode

# Custom host/port override
debug-pilot setup --debugger=xdebug --ide=vscode --host=192.168.1.5 --port=9000

# Configure specific Xdebug modes
debug-pilot setup --debugger=xdebug --ide=vscode --xdebug-mode=debug,develop,coverage

Setup Options

Option	Description	Default
`-p`, `--project-path`	Root path of your project (where IDE config is written)	Current directory
`-d`, `--debugger`	Debugger to configure (`xdebug`)	(Prompts user)
`-i`, `--ide`	IDE to configure (`vscode`, `sublime`)	(Prompts user)
`--host`	Xdebug client host IP	`auto` (detects Docker host or `localhost`)
`--port`	Xdebug client port	`9003`
`--xdebug-mode`	Xdebug modes, comma-separated (`debug`, `develop`, `coverage`, `profile`, `trace`)	(Prompts user with current modes pre-selected)

🐳 Using with Docker

Generating Docker Config

Use the init-docker command to generate ready-to-use Docker configuration snippets:

# Generate an Xdebug Dockerfile snippet (printed to stdout)
debug-pilot init-docker

# Also create a docker-compose.debug.yml override file
debug-pilot init-docker --write-compose

Dockerfile Setup

Add the generated snippet to your Dockerfile (after FROM php:8.x-*):

# === PHP Debug Pilot — Xdebug Configuration ===
RUN pecl install xdebug && docker-php-ext-enable xdebug
RUN echo 'xdebug.mode=debug' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo 'xdebug.client_host=host.docker.internal' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo 'xdebug.client_port=9003' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Docker Compose Override

Use the --write-compose flag to generate a docker-compose.debug.yml:

debug-pilot init-docker --write-compose

Then run with both files:

docker compose -f docker-compose.yml -f docker-compose.debug.yml up

Running Debug Pilot Inside a Container

You can run debug-pilot directly inside a running container. On official PHP Docker images (php:*), it will auto-install extensions for you:

# Enter your container
docker exec -it my-php-container bash

# Install debug-pilot
curl -sLO https://github.com/Gemui/php-debug-pilot/releases/latest/download/debug-pilot
chmod +x debug-pilot && mv debug-pilot /usr/local/bin/

# Run the interactive setup (auto-detects Docker, resolves host.docker.internal)
debug-pilot setup

💡 Tip: Debug Pilot automatically detects Docker environments and resolves host.docker.internal as the debug client host. On Linux Docker, it discovers the gateway IP from /proc/net/route.

Init Docker Options

Option	Description	Default
`-d`, `--debugger`	Debugger to configure (`xdebug`)	`xdebug`
`--port`	Debug client port	`9003`
`--write-compose`	Write `docker-compose.debug.yml` to project	`false`
`-p`, `--project-path`	Project root path	Current directory

🖥️ Supported Platforms

Operating Systems: macOS, Linux, Windows, Docker Containers
Debuggers: Xdebug 3+
IDEs: VS Code, Sublime Text 3/4

🔧 Troubleshooting

"Extension is not installed" warning?

Run debug-pilot install <extension> (or toggle) and follow the interactive prompts to install it. Or install manually:

macOS: pecl install xdebug
Ubuntu: sudo apt install php-xdebug
Docker: RUN pecl install xdebug && docker-php-ext-enable xdebug

"Cannot write to php.ini"?

Run the tool with sudo if your php.ini is system-protected:

sudo debug-pilot setup

PHAR not working?

Ensure the PHAR has execute permissions:

chmod +x debug-pilot

If you encounter "command not found", verify /usr/local/bin is in your $PATH:

echo $PATH | grep -q "/usr/local/bin" && echo "✅ Path is set" || echo "❌ Add /usr/local/bin to PATH"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Made with ☕ by Gemui

gemui / php-debug-pilot

Maintainers

Package info

Statistics

Security