How debug PHP applications with Dephpugger

DePHPugger is a tool to debug your php applications using any framework for web or your php CLI codes. You can see in terminal, without need install an IDE to use. Is very simple and usefull. See an example bellow:

https://www.youtube.com/embed/TUTqby-LbuQ

Dephpugger demonstration

Why?

In other languages (like Python and Ruby), is really normal start a web server in terminal and start to develop your application code. In PHP, many people install NGINX or Apache to run an application in local development. But, after PHP 5.4, you can start web server with a simple command.

$ php -S localhost:8080 # Open http://localhost:8080

I prefer this mode, because I only need install PHP.

If you are a Python developer and want start a debug in a breakpoint to check your code, you can use the lib IPDB, and in the same server you will see the code stopping and in terminal will appear the code lines.

In ruby language is very similar, you can install the lib Byebug and start use. The breakpoint is only write “byebug” and refresh your page.

But, if you are a PHP developer, you must install xDebug first, choose an IDE or editor, search for a tutorial how integrate <my editor> with xDebug. If you want change the IDE, you must configure your new IDE again. This is really bad, because many developers can't install and prefer to use var_dump($variable); die() (or print_r($variable);exit; to see a variable value in each request.

Now you can run the server and the debugger in terminal in an easy installation.

Dephpugger (left) vs IPDB (right)

Dependencies

The dephpugger use a few libs in PHP to run the debugger.

• PHP 7.0 or more (not tested in older versions)
• XDebug
• Composer
• A Plugin for your browser (If you want to debug a web application)

To debug a web application you must install a plugin to your browser. There area plugins for Plugins for Chrome, Firefox, Safari and Opera.

Dephpugger Installation

To install the dephpugger lib, you must use the composer first. You can install in global mode or in local mode (inside the project, not recommended).

In this tutorial, we will install in the global mode. First, you need run in terminal:

composer global require “tacnoman/dephpugger”:”dev-master”

This command will install the dephpugger in path $HOME/.composer/vendor. In the vendor directory exists a folder bin with the dephpugger. We need add this directory to the environment variable $PATH.

Open the file ~/.bash_profile and add this:

export PATH=$PATH:$HOME/.composer/vendor/bin

Now, run:

$ source ~/.bash_profile

Now you can run the command dephpugger.

Configuration to use

You can run the command dephpugger requirements to see if all is ok. You will see something like this:

Dephpugger requirements command

Usage

If all is ok, create a directory to your project.

$ mkdir /path/to/the/project$ cd /path/to/the/project

No create a file called index.php.

<?php# File index.php$array = [0,2,1,3,4];

xdebug_break(); # <-- Important line. This line is a breakpoint

$array = sort($array);

echo implode(‘, ‘, $array);

With the terminal in folder, run the dephpugger server.

$ dephpugger server

Dephpugger server example

Now, open a new tab (in terminal) and run the code:

$ dephpugger debug

You will see this in terminal.

Dephpugger debug

Open your http://localhost:8888 again. The code won’t stop in breakpoint, because you need active the browser's plugin. In this tutorial I will show how to use in Chrome.

Chrome plugin to xDebug

First, click in debug and you need see the debug with a green color, like the image bellow.

Chrome plugin enabled

Now, refresh the page with http://localhost:8888 and see the magic. In this terminal tab you will see this.

Debug in dephpugger lib stopped in a breakpoint

Now you have a breakpoint in your code. The function xdebug_break(); is a breakpoint to stop the code. Now you can navigate and investigate the code to find bugs. Equals in IPDB to Python and Byebug to Ruby.

List of commands:

• n -> To run a step over in code
• s -> To run a step into in code
• set <cmd>:<value> ->Change verboseMode or lineOffset in runtime
• c -> To continue script until found another breakpoint or finish the code
• l -> Show next lines in script
• lp -> Show previous lines in script
• helph -> Show help instructions
• $variable -> Get a value from a variable
• $variable = 33 -> Set a variable
• my_function() -> Call a function
• q -> Exit the debugger

You can see this list always updated in this link.

Configuring your project

Now you can use the Dephpugger to debug your applications, but Dephpugger is flexible and is really easy to configure. Is possible, with a simple file, change the default web server build-in port, change the public path, the file to run…

In your root project folder, you must create a file called .dephpugger.yml . This is the parameters.

---debugger:host: localhost # Host to debuggerport: 9005 # Port to debuggerlineOffset: 6 # How many lines will show in each breakpointpath: ./public/ # default: null - Folder to root pathfile: index.php # default: null - File to root pathverboseMode: false # default: false - Only to dephpugger devshistoryFile: ~/.dephpugger_history # File with history commandsserver:host: localhost # Host to your applicationport: 8000 # Port to run your application

You can see in official website, the basic configuration to Laravel, Lumen, ZF2 (Zend Framework 2), Symfony, Slim Framework, Silex and Yii2.

Dephpugger CLI commands

To debug CLI commands, you can open the debugger in one terminal, and in another terminal use this command:

$ dephpugger cli /path/to/cliFile.php

This command will run your command with the Dephpugger debug.

See ya!

That’s all folks. You can see more details in our official website or in our repo in github. Follow us!

Tacnoman!

Dephpugger logo