Documentation

If you already have Xdebug properly installed in your system skip to “Installing Codebug” section.

As you know Codebug is a client interface for Xdebug, so, with that in mind you will need to configure both server and client. On codebug there’s little to configure, however, if you don’t have Xdebug you will need to install it and configure on the server you have your PHP files.

Requirements

OS: Mac OSX 10.7+ and Xdebug: Xdebug 2.x

As you will see, you don’t need Xdebug installed on your local machine, however, you will need it on the machine you will be debugging your code.

Installing Xdebug on Linux

If you are using a remote or even a virtualized linux server you will need to install Xdebug on that machine. The best way to do this is to go to http://xdebug.org/docs/install . You will find the official updated installing procedures from Xdebug.

Installing Xdebug on Mac (MAMP)

This installation instructions applies to the most recent version of MAMP at the time of the writing of this document, which was: 2.1.1.

MAMP already includes Xdebug, however it’s commented out in the php.ini file.

You have to do is edit php.ini:

Step 1

Edit php.ini Launch your regular text editor and edit the file located at “/Applications/MAMP/bin/php/php5.4.4/conf/php.ini”

Step 2

Uncomment Xdebug extension At the end of this file will find this lines:

[xdebug]
;zend_extension="/Applications/MAMP/bin/php/php5.4.4/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so"

Just uncomment the second line by removing “;” at the beginning, so it becomes:

[xdebug]
zend_extension="/Applications/MAMP/bin/php/php5.4.4/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so"

Step 3

Restart MAMP Open the MAMP control window and restart Apache by clicking on “Stop Servers” and “Start Servers”

Test Xdebug installation

MAMP users

Go to, click on “Open Start Page” and after the page loads in your browser click on “PHPInfo” link at the top menu. Search for “Xdebug” you should find something link this:

image00-300x226

Linux users

First make sure your restart Apache/Nginx or PHP-FM.

On the console type:

php -m | grep xdebug

If the output was “xdebug” you are ready up and running.

Installing Codebug

This is the easiest part, after you download Codebug from our website, double click on the DMG file and drag the Codebug into your Applications folder.

dmg


The configuration of Codebug and Xdebug is splitted in two different parts, let’s first configure

Xdebug.

Configuring Xdebug

MAMP Users

open the file “/Applications/MAMP/bin/php/php5.4.4/conf/php.ini”.

Linux Users

It varies from system to system, but normally Xdebug has it’s own configuration file, on Debian

server it normally lives in “/etc/php5/conf.d/xdebug.ini”

Now edit it’s contents so it’s something like this:

[xdebug]
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.remote_connect_back=1
;xdebug.remote_host=192.168.1.108
zend_extension = /usr/lib/php5/20090626+lfs/xdebug.so
The parameter zend_extension may differ from the one used in our example. Do not change this in your file.

For a more detailed explanations on this settings please visit: http://xdebug.org/docs/all_settings

Now save the configuration file and restart your PHP server.
If all goes well Xdebug is ready to work.
Again, please notice that Codebug will act has a server and not the other way around, so Xdebug will try to connect to the Codebug. In this in mind, you need to open up your firewall port on the machine where Codebug is if you are on a external network.

On LANs you normally don’t need to touch any of you firewall configurations, but again, it may
varies from case to case. To simplify this, here’s a diagram of how Xdebug works with Codebug:

image04

1 Someone makes a request to some page eg: http://localhost/myPage.php
PHP interpreter will be called since it’s a PHP page.
3 Since Xdebug is enabled, PHP will automatically call Xdebug, this will only happens if “remote_autostart” in your configuration file is set to 1. Otherwise Xdebug will ignore the request.
4 Xdebug will then connect to the “remote_host” or the IP address of the user who requested the page if “remote_connect_back” is enabled. After connecting, the PHP script will be halted and it will wait for instructions from Codebug.
5 Codebug will see display the source code for that script and you will now be able to debug your code.
6 Whatever instruction your use from Codebug, this will sent that request to Xdebug to either continue, step into, step over, step out or even change a variable value
7 As soon as the debugging stops PHP will continue to process the script
8 Output will be sent to browser

Configuring Codebug

To configure Codebug for Xdebug go to “Codebug” > “Preferences” or press: “cmd + ,”. Select “Xdebug” this window should appear.

image17

  • Listen on Port The port where Codebug will be waiting for Xdebug connections
  • Session ID You can specify a session ID, so that codebug will only work if the server is also sending the same session id. You need to add “xdebug.idekey=”someID” to your Xdebug configuration file in order for this to work.
  • Max Children It lets you specify how many children elements you want to receive, like arrays, objects etc.
  • Max Data How much data do you want variables to hold, for unlimited data type “-1”
  • Max Depth How many nested levels or arrays or elements you want to allow, the more you add the more slow the connections gets. Causion with this one
  • Break on first lineIf this is on, the PHP script will always stop at the first line of the PHP script.

Themes

To select a new Theme go to “Codebug” > “Preferences” or press: “cmd + ,”.
Select “Themes” this window should appear.

image16

You can select a theme for Codebug, this themes only affects the source code viewer.

Path Mapping

By default, Codebug will always request the source code directly to Xdebug, so you don’t have to configure anything. This is very useful if you are debugging remote files and you happen to have the same copy in your local computer. This way the communication between Xdebug and Codebug is much more faster.

To create a path mapping it’s very simple.
Go to “Codebug” > “Preferences” or press: “cmd + ,”.
Select “Paths” this window should appear.

image03

To add a path just click on the plus (+) sign button.
You need to add the full path for each section.
To remote just select the row you want and click the minus (-) sign button.

If the server and local paths are the same you don’t have to do this. Codebug will automatically match it for you.


If you follow the installing and configuration instructions and everything is up and running you are ready to use Codebug.

  • Step 1 Open codebug
  • Step 2  Click on the power button power so it becomes blue. This means Codebug is ready to accept any connections.
  • Step 3 On your PHP script, just type “xdebug_break();” above the line you wish codebug to stop. Make sure that the below line where “xdebug_break()”  is declared it’s a simple statment or a compound statement. This won’t work if you use it above a “Class” or a “function” declaration. Another good alternative is to use it in the same line as the code you want to break.
  • Step 4 From the browser, make a request to a php script that you know will call that PHP file somehow
  • Step 5 Codebug should automatically open up, and something like this should be visible

image09

  •  Step 6 If you get something like this it means your configuration and installation is all good and you can now use Codebug. If you don’t see the inspector window, press: CMD + Alt + I, or click “Stack” at the left bottom button.


As soon as the a script is halted form Xdebug, Codebug will enable the debugging buttons.

Using this will allow you to watch a step-by-step as you code is being executed. If you never used a debugger before you will find this very useful, because you will be able to see how PHP processes your code.

buttons

From left to right:

  • Continue Lets the script run as it would normally until it hits another breakpoints, or xdebug_break(); in your code. If none is found, the script is done.
  • Step Into Steps into a block of code/function/etc.. for further analysis
  • Step Out Steps out of a block of code
  • Step Over Bypasses the next instruction


Like stated in the Quick Start section, you can just type “xdebug_break();” directly into your code. That’s enough to make Codebug start.

However, there will be times where you don’t want to do this, because you don’t have access to the remote file, or because you visually define where the code breaks.

A breakpoint is a instruction Codebug sends Xdebug, to let him know which file and line you want the interpreter to halt.

Unlike xdebug_break(); function call, using breakpoints is a more cleaner, because you don’t have to change your source code at all. It can all be done from Codebug.

Creating a breakpoint

To create a breakpoint all you need to is to click on the left side of the line number, it will create a red dot.

image13

You can create a breakpoint when the debugger is running, so the next time it starts it will stop there.

File Explorer

A better way of doing this tho, is from the File explorer.
To access the file explorer press: cmd + e or go to “Codebug” > “Show File Explorer”, a window should appear at the left side of your app.

dragdrop

You just need to drag a folder from Finder to that Drawer or to the App icon, then all you need to do is to browse to file you want and double click it.

Also, when you set a breakpoint it will be saved for later use. So even if you terminate Codebug app and start it again, the breakpoint will be ready for a next session.

Removing a breakpoint

To remove it, just click on the red dot again.


You can access the inspector window by click on “stack” at the bottom left button, or pressing CMD + ALT + I.

stack

The inspector window has two frames, Stack and Breakpoints

Stack Frame

The stack frame will be filled when the debugging actually starts. From where you can change stack frames, and explorer your variables and also change it’s contents.

At the left side it’s your Stack frame, the current stack it’s always the first on that list

image01

At the right are your script variables content at the moment of the script:

image14

You can easily browse those and double click on the value data to change it’s value. That change will immediately be reflected in the processing PHP code at the next iteration.


Breakpoints Frame

You can access the Breakpoints frame by click “stack” button and pick “Breakpoints” or press CMD + ALT + B.

image12

The breakpoints frame is a breakpoints manager in a nutshell. From here you can access all of your created breakpoints, and you can create, update and remove any previously set breakpoints.

So if you have many files with many breakpoints, you can just easily manage it from here instead of opening each file.

Console

This is a beta featured

The console allows you to interact directly with your code by passing evaluating expression during a debugging session. You can even create variables on the fly.

Screen Shot 2014-02-25 at 22.12.44 2014-02-28 11-10-58 2014-02-28 11-11-02

You can type a name of a variable to inspect it, or you can evaluate expressions on the-fly.

Watches

This is a beta featured

Watches are a great way to keep an eye on a variable or expression that you wish to track during a debugging session. It removes the need to type that expression every single type you step into another stack.

Screen Shot 2014-02-28 at 11.13.40

 

To set up a new expression, just click on the “+” icon, double click the new expression entry field name, type your expression and press enter.

  • Active - Actives/disables the evaluation of the expression
  • Expression - The piece of code you wish to test
  • Result - The result of the evaluation of the expression



⌘ + O Opens file dialog
⌘ + S Starts or Stops the Codebug listening
⌥ + ⌘ + → Continue
⌥ + ⌘ + ↓ Step Into
⌥ + ⌘ + ← Step Over
⌥ + ⌘ + → Step Out
⌥ + ⌘ + S Shows Stack Frame
⌥ + ⌘ + B Shows Breakpoints Frame
⌥ + ⌘ + C Shows Console & Watches Frame
⌥ + ⌘ + I Shows Inspector Window
⌘ + I Closes Inspector Window
⌘ + , Shows preferences Window


Codebug introduced a new OSX Protocol that allows you to communicate with it from anywhere, even from a terminal window

To more information on this check the topic API. 

However, we noticed that lots of users use Codebug with Sublime Text.  So we created this Sublime Text addon to help work set breakpoints and start Codebug directly from Sublime Text.

How to install Sublime Text addon

You can do that in two ways:

  • If you have Package Control installed, all you have to is press cmd + shift + p, type “install” and search for “Codebug”. Restart Sublime Text and your are done.

How to use it

Whenever you are working on a piece of code you want to set a breakpoint to debug it, just select that line and press cmd + alt +b and Codebug will open automatically with that file and a breakpoint will be set at the current selected line on Sublime Text

Just that easy.

Codebug now includes a OSX Protocol API. This protocol allows any application to interact with Codebug from outside.

Example

codebug://send?file=<full local file path>&line<line number>&op=<operation type>&open=<1|0>

To use it from a terminal window you just need to type:

“$ open codebug://<params>” 

Here’s a breakdown of the parameters:

  • file (string) - The full local path of the file you want to open in Codebug
  • line (int) - Line number of where the breakpoint should be set
  • op (string) - Type of operation, currently we included two: add - add a new breakpoint, delete - remove breakpoint
  • open (bool) - If set to 1 it will open the file in Codebug, otherwise it will just create or remove the breakpoints for that file.

There’s plans to include more options in the near the future.