Custom-Configuring Xdebug with Nanobox

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.

# from the root of your project
nanobox run  

Scott Anderson

Designer, code-dabbler, writer, foodie, husband, and father. Core Team Member at Nanobox.

Subscribe to Nanobox

Get the latest posts delivered right to your inbox.

or subscribe via RSS with Feedly!