Xdebug is a powerful, open source debugging/profiling tool for PHP. It's packaged as a PHP extension and can be incredibly helpful when fine-tuning your PHP application. Xdebug has many configurable options available that are handy for configuring Xdebug to your specific needs or integrating it with an IDE like PHPStorm. Using custom Xdebug configs in a Nanobox environment is simple, but does requires a little setup.

Include Xdebug in Your Project

The PHP Engine lets you specify what Zend extensions to include in your project with the zend_extensions config in your boxfile.yml , the file used to define and configure your app's environment. For performance reasons, I recommend including Xdebug only in your local dev environment, which is done using the dev_zend_extensions > add config in your boxfile.yml :

run.config: engine: php engine.config: dev_zend_extensions: add: - xdebug

Create a Custom xdebug.ini

To define non-default Xdebug settings, include a custom xdebug.ini in your project.

Note: You only need to include the settings you want to modify in the xdebug.ini .

xdebug.remote_enable=1 xdebug.remote_host=123.45.67.89 xdebug.remote_port=9000 xdebug.remote_handler=dbgp

Include Your Custom xdebug.ini in the Build Process

When you run nanobox run , Nanobox will build and prepare your app's runtime. You can include extra_steps in your boxfile.yml to run custom commands during the build process. Use an extra step to copy your custom xdebug.ini into /data/etc/php.dev.d , the directory where development runtime configs are stored by the PHP engine.

run.config: # ... extra_steps: - cp xdebug.ini /data/etc/php.dev.d/xdebug.ini

Everything for Xdebug in the boxfile.yml

With everything for Xdebug included, this is what your boxfile.yml will look like:

run.config: engine: php engine.config: dev_zend_extensions: add: - xdebug extra_steps: - cp xdebug.ini /data/etc/php.dev.d/xdebug.ini

That's It!

With your custom xdebug.ini in place and everything in your boxfile.yml , start up your dev environment and your custom Xdebug configuration will be used.