xrDebug 1.0

Lightweight portable debug utility

rodber   GitHub

I'm glad to announce the first stable release of xrDebug. Head over to docs.xrdebug.com to start using it now!

# Hello, xrDebug

xrDebug is a dump debug server, which displays dump messages in a dedicated user interface. Instead of throwing debug information to an output stream, xrDebug shows this information in a web application with support for multiple peers. It can receive messages from n-sources and stream the debug window to n-clients at the same time.

The system consists in a web server (SSE) plus client libraries enabling users to easy send messages to. The server is a command line application made with Chevere and ReactPHP.

xrDebug cli

User interface is provided with a single page application and there's an HTTP API spec provided by Schwager describing the interaction with the server. As it is HTTP based, xrDebug can work with any programming language long as you can send HTTP requests to it.

Software is available for multiple architectures including arm64 and x86_64, for macOS, Linux and Docker.

# Application

User experience starts with a splash screen which indicates software version, features enabled and keyboard shortcuts.

xrDebug splash

Once messages starts to get streamed the user interface changes to the main view, with a top section showing session name and stream controls. The rest of the user interface is for listing messages.

xrDebug main

Session name is editable, customizable at anytime on user interface and at server spawn with xrdebug -n "MyDebugger".

xrDebug controls

Buttons resume, pause and stop enable to handle message streaming. When pausing, the system will indicate pending message deliveries. The clear button removes all messages from view.

xrDebug controls

Each message has action buttons for removing a message from list, copy to clipboard and export to image. Message content includes topic, emote, body, file + line and time.

xrDebug message

Both topic and emotes enables message filtering, the difference is that when using topic you filter by word and when you use emote it filters using emoji. You can combine filters.

xrDebug filters

# Feature list

Taken from the repo:

  • Ephemeral, it doesn't store any persistent data
  • Signed requests (Ed25519)
  • End-to-end encryption (AES-GCM AE)
  • Filter messages by Topics and Emotes
  • Resume, Pause, Stop and Clear debug window controls
  • Keyboard shortcuts (Resume R, Pause P, Stop S and Clear C)
  • Re-name "xrDebug" session to anything you want
  • Export dump output to clipboard or as PNG image
  • Pause and resume your code execution
  • Dark / Light mode follows your system preferences
  • Portable & HTML based (save page, search, etc.)
  • Uses FiraCode font for displaying beautiful looking dumps
  • Open with editor links
  • Responsive user interface

# PHP Features

Taken from the repo:

  • Configuration via code and xr.php file
  • Dump arguments using VarDump
  • Generates dump backtrace
  • Custom inspectors
  • Handle errors and exceptions (hook or replace your existing handler)

# Distribution

xrDebug is Open Source software is distributed under the Apache 2.0 license and all build artifacts are created on CI.

# Binary

Self-contained binary builds are available for macOS (Apple Silicon, Intel) and Linux (aarch64, x86_64). Simple as download and execute, no system pre-requisites as everything is included in the binary file.

Binary distribution feat is possible thanks to phpmicro. At xrdebug/xrdebug-micro I've a forked dixyes/lwmbs with CI for creating my own micro.sfx artifacts tailored for xrDebug.

Compared to Docker there's no competition as the latter requires to install a container runtime plus all the hassle of managing these containers. Binary xrDebug is a single ~30MB file that you put in your filesystem to execute and that's all! For macOS users the install process is simple as a double-click on the xrdebug.pkg package.

xrDebug macos

# xrdebug.phar

The xrdebug.phar file packages the source code and vendor dependencies. To execute this PHAR file it requires PHP installed in your system.

The PHAR file is possible thanks to the box project.

# Composer

There is xrDebug package at Packagist which you can require to bundle it in your project. To use the Packagist package it requires Composer installed in your system.

# Docker

Docker container images are available at xrdebug/xrdebug. To use container images it requires Docker or any other container runtime installed in your system.

# Language features

xrDebug is PHP software and the default client library is also for PHP at xrdebug/php. There are neat PHP exclusives like custom inspectors and throwable handler integration.

xrDebug throwable

I must remark that xrDebug is language agnostic as its HTTP API enables that other languages, CMS, frameworks or anything can provide their own client library addressing specific user needs.

The server software is a fancy message stream. Is the client library which provides the debug feature.

# xrDebug needs your contribution

At this time xrDebug client library catalog is limited to PHP. Help is welcome and gladly appreciated as it enables to bring xrDebug to more languages and platforms.

Read the developer guide to get started creating a client library.

If you use xrDebug or think that it will help someone feel free to spread the word about it. Hope more people will use it.

Rodolfo blogging since 2012.