PHPackages gemui/php-debug-pilot - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. gemui/php-debug-pilot ActiveLibrary[CLI & Console](/categories/cli) gemui/php-debug-pilot ===================== An extensible CLI platform to manage PHP runtime debug configurations. v1.0.0(4mo ago)18MITPHPPHP >=8.2 Since Feb 24Pushed 4mo agoCompare [ Source](https://github.com/Gemui/php-debug-pilot)[ Packagist](https://packagist.org/packages/gemui/php-debug-pilot)[ Docs](https://github.com/Gemui/php-debug-pilot)[ RSS](/packages/gemui-php-debug-pilot/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (8)Versions (4)Used By (0) [![PHP Debug Pilot Logo](art/logo.png)](art/logo.png) PHP Debug Pilot πŸš€ ================= [](#php-debug-pilot-) [![Latest Stable Version](https://camo.githubusercontent.com/30b86a0aa36536d4c4fbfc8030b79f6a3746e7d1160268c5cd0f2dd731999cfe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67656d75692f7068702d64656275672d70696c6f742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gemui/php-debug-pilot)[![PHP Version](https://camo.githubusercontent.com/0d21dfe81999f32db35664c0d2165469c7c0cfe28916870c0ec51beedbdb1372/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f67656d75692f7068702d64656275672d70696c6f742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gemui/php-debug-pilot)[![License](https://camo.githubusercontent.com/6de697c87647c0b0c7501de7985f5c61bb5aa9b0973e01a63a396d4d635cf252/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f67656d75692f7068702d64656275672d70696c6f742e7376673f7374796c653d666c61742d737175617265)](https://github.com/Gemui/php-debug-pilot/blob/main/LICENSE)[![Total Downloads](https://camo.githubusercontent.com/6f19e27e5135d5b64e19c7bc883a5151bf9244608a07836ef30cdd35c968c94f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f67656d75692f7068702d64656275672d70696c6f742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/gemui/php-debug-pilot)[![GitHub Releases Downloads](https://camo.githubusercontent.com/9b00b905d4ccf18faf77170f6c8a9cdfb33efa76523f579e9b1c78776c13a8c8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f646f776e6c6f6164732f47656d75692f7068702d64656275672d70696c6f742f746f74616c3f7374796c653d666c61742d73717561726526636f6c6f723d626c7565266c6162656c3d50484152253230446f776e6c6f616473)](https://github.com/Gemui/php-debug-pilot/releases) **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 ---------- [](#-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 -------------- [](#-installation) ### Requirements [](#requirements) - **PHP** `^8.2` - **Composer** (for Method 2 & 3 only) ### Method 1: Standalone PHAR (Zero Dependencies) [](#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) [](#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 [](#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 ---------- [](#-updating) ### Method 1: PHAR [](#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 [](#method-2-global-composer) ``` composer global update gemui/php-debug-pilot ``` ### Method 3: Per-Project [](#method-3-per-project) ``` composer update gemui/php-debug-pilot ``` --- πŸš€ Usage ------- [](#-usage) ### Interactive Setup [](#interactive-setup) Run the setup wizard to configure extensions and generate IDE files: ``` debug-pilot ``` The tool will: 1. πŸ” Detect your environment 2. πŸ› Ask which debugger you want to configure (Xdebug) 3. πŸ’» Ask which IDE you use 4. βœ… Write the configuration and verify the setup ### Check Status [](#check-status) See which extensions are installed and enabled: ``` debug-pilot status ``` **Output:** ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Driver β”‚ Installed β”‚ Enabled β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ xdebug β”‚ βœ… β”‚ βœ… β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### Enable / Disable Extensions [](#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 [](#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 [](#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 [](#setup-options) OptionDescriptionDefault`-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 ------------------- [](#-using-with-docker) ### Generating Docker Config [](#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 [](#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 [](#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 [](#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 [](#init-docker-options) OptionDescriptionDefault`-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 pathCurrent directoryπŸ–₯️ Supported Platforms ---------------------- [](#️-supported-platforms) - **Operating Systems:** macOS, Linux, Windows, Docker Containers - **Debuggers:** Xdebug 3+ - **IDEs:** VS Code, Sublime Text 3/4 --- πŸ”§ Troubleshooting ----------------- [](#-troubleshooting) ### "Extension is not installed" warning? [](#extension-is-not-installed-warning) Run `debug-pilot install ` (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"? [](#cannot-write-to-phpini) Run the tool with `sudo` if your `php.ini` is system-protected: ``` sudo debug-pilot setup ``` ### PHAR not working? [](#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 -------------- [](#-contributing) Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- πŸ“„ License --------- [](#-license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- πŸ™ Acknowledgments ----------------- [](#-acknowledgments) **Made with β˜• by [Gemui](https://github.com/Gemui)** ### Health Score 36 β€” LowBetter than 79% of packages Maintenance76 Regular maintenance activity Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 3 Last Release 129d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f6b9185439685b7e65e7680b95ed9651d634c8f8509390a2473304bf4e511674?d=identicon)[Gemui](/maintainers/Gemui) --- Top Contributors [![Gemui](https://avatars.githubusercontent.com/u/44297379?v=4)](https://github.com/Gemui "Gemui (28 commits)") --- Tags phpclidebugDevtoolsXdebug ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/gemui-php-debug-pilot/health.svg) ``` [![Health](https://phpackages.com/badges/gemui-php-debug-pilot/health.svg)](https://phpackages.com/packages/gemui-php-debug-pilot) ``` ### Alternatives [nunomaduro/termwind It's like Tailwind CSS, but for the console. 2.5k271.5M385](/packages/nunomaduro-termwind)[mehrancodes/laravel-harbor A CLI tool to Quickly create On-Demand preview environment for your apps. 10097.5k](/packages/mehrancodes-laravel-harbor)[nunomaduro/laravel-console-task Laravel Console Task is a output method for your Laravel/Laravel Zero commands. 2592.3M13](/packages/nunomaduro-laravel-console-task)[alecrabbit/php-cli-snake Lightweight cli spinner with zero dependencies 29216.7k5](/packages/alecrabbit-php-cli-snake) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)