Composer/Xdebug-Handler
Restarts CLI processes without loading the Xdebug extension to improve performance.
What is Composer/Xdebug-Handler?
Composer Xdebug Handler is a PHP library that automatically restarts command-line interface (CLI) processes without loading the Xdebug extension, unless it's explicitly disabled. It solves the performance overhead of Xdebug during routine tasks like dependency management by transparently restarting processes in an Xdebug-free environment. Originally part of Composer, it is now a standalone tool for seamless integration into PHP CLI applications.
PHP developers working with command-line tools or scripts that need to avoid Xdebug's performance impact during non-debugging operations, such as running Composer, PHPUnit, or other CLI-based utilities. It is particularly useful for tool maintainers who want to ensure their applications run efficiently without requiring users to manually disable Xdebug.
Developers choose this library because it automatically handles the restart process transparently, eliminating the need for manual configuration or user intervention. Its unique selling point is the ability to keep Xdebug available for debugging while avoiding its slowdown in everyday CLI tasks, with extensible design for custom restart logic and support for persistent settings across sub-processes.
Overview
Restart a CLI process without loading the xdebug extension.
Use Cases
Best For
- Automatically disabling Xdebug in PHP CLI tools like Composer to speed up dependency installation and updates.
- Building PHP command-line applications that need to run efficiently without Xdebug overhead during normal operation.
- Managing PHP sub-processes in scripts where Xdebug should be excluded to maintain performance.
- Extending restart logic for custom ini file modifications, such as adjusting settings like phar.readonly.
- Integrating Xdebug handling into development workflows where debugging is needed intermittently but performance is critical for routine tasks.
- Providing seamless Xdebug-free environments in CI/CD pipelines for faster build and test execution.
Not Ideal For
- Web applications requiring Xdebug management in HTTP request contexts, as it's designed solely for CLI processes.
- Projects where Xdebug must remain loaded at all times for continuous debugging, making automatic restarts counterproductive.
- Environments with strict security policies that restrict process spawning or modification of ini files.
- Development setups using alternative debuggers like Zend Debugger or DBG, since it only targets Xdebug.
Pros & Cons
Pros
Transparently restarts CLI processes without Xdebug to avoid slowdowns, using environment variables like MYAPP_ALLOW_XDEBUG for control, as shown in the Basic Usage section.
Offers protected methods like requiresRestart() and restart() for custom modifications, such as adjusting ini settings like phar.readonly, demonstrated in the Extending the library example.
Provides static utilities like getAllIniFiles() and getRestartSettings() to access original configurations in restarted processes, detailed in the Helper methods section.
Includes built-in support for asynchronous signals (e.g., SIGINT) and Windows control events, ensuring clean process management as described in the Signal handling subsection.
Cons
Extensions specified via command-line arguments are not loaded in restarted processes, a admitted limitation in the README that can break tools relying on them.
Extending the library for custom logic requires overriding protected methods and careful parent calls, increasing development overhead compared to simpler solutions.
Restarts can fail if temporary ini files cannot be created, necessitating troubleshooting with XDEBUG_HANDLER_DEBUG, as shown in the logging examples, which adds uncertainty.
Frequently Asked Questions
Related Projects
OctoLinker Browser ExtensionOctoLinker — Links together, what belongs together
Composer-UnusedShow unused composer dependencies by scanning your code
StudioA workbench for developing Composer packages.
Composer-Normalize🎵 Provides a composer plugin for normalizing composer.json.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.