Open-source project
xdebug/xdebug avatar
xdebug/xdebug

Xdebug: opt-in features, four CI configurations, and a license of its own

Xdebug — Step Debugger and Debugging Aid for PHP

3,418 stars598 forksPHPNOASSERTION

At a glance

What is it?
Xdebug is the PHP step debugger and development aid, written in C and built as a PHP extension. Its README is written in reStructuredText with badges for three hosted services and a third-party analytics block, its features are individually switched on, and its licensing is a custom file that it says is open source without claiming approval.
Who is it for?
Xdebug is the default answer for stepping through PHP, and its design explains why it is also the usual suspect when a site feels slow: features are opt-in individually, so the only reliable way to know what is running is the setting list, and the file points to a documentation set with over a hundred settings rather than pretending the defaults are self-evident. Three things to check.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 11 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • xdebug/xdebug3,418 ★ · +3
Star history
Repository2026-09-242026-11-15
xdebug/xdebug3.4k3.4k

3 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every feature is opt-in, and the step debugger also needs a client

The configuration model is the thing to understand first, because it explains both the flexibility and the folklore about this extension slowing everything down.

Most features have to be opted into, and each one has its own switch. The example given is the step debugger, which you enable by setting `xdebug.remote_enable=1` in your configuration file. Nothing is enabled by being present in the extension.

The step debugger has a second requirement that catches people out: it requires an IDE acting as the client. The file links to a list of available clients rather than shipping one, so the debugger half of the setup is a pairing between two programs.

Everything else is described the same way, by pointing at documentation. There is a page per feature, and a separate full list of all settings, and the file notes there are over a hundred settings and many functions documented in total. So the README is an index and the documentation site is the specification, which is the right division for a tool with this many switches and also the reason a precise question about a default cannot be answered from the file alone.

Install is a distribution package or the pie installer, and nothing else

Two routes, and they are mutually exclusive in practice.

The first is the distribution. On most Linux distributions Xdebug can be installed through the system package manager, and the file names the package that is most often used. That route means your PHP version, your distribution's build flags and Xdebug's version are decided by whoever maintains that package.

The second is the pie installer, which the requirements section calls for unless the distribution already has a package. The command is short:

bash
pie install xdebug/xdebug

That route is stated to work on Linux, macOS and Windows, which makes it the portable choice and also the one where you own the version.

Underneath both is a hard requirement: a supported version of PHP, linked from the language's own list of supported versions. There is no compatibility shim for an unsupported release, so an extension that refuses to install on an old PHP is following the stated rule rather than failing unexpectedly.

Longer instructions, including building from source, live on the documentation site under the installation section rather than in this file.

Four continuous integration configurations share one repository

The top level is where the infrastructure shows through. There is a hosted pipeline configuration file with its own directory beside it, a CircleCI directory, a directory whose name is the project's own abbreviation, and a GitHub directory that is the target of the test badge at the top of the file.

That is four continuous integration setups in one tree. Some of that is history: a project that predates one system keeps its configuration when it moves to the next. The practical consequence today is that the badge at the top of the file tells you one of those systems is the one that gates the branch, and the others may be running for releases, for a specific platform, or not at all.

The same pattern appears in the build files. There is an autoconf-style configuration for Unix, a separate one for Windows, a fragment that is included by a makefile rather than being one itself, an m4 directory for the macros those configuration files use, and a shell script whose job is to rebuild. There is also a Windows resource template and a gdb initialisation file for working with the extension under a debugger.

None of that is in the instructions, and all of it is in the tree, which is the fastest way to tell what a project actually runs.

The extension ships its own defaults, its own stubs and two package manifests

Several root files exist because this is a PHP extension rather than a library, and each one tells you something about the build.

There is a shipped settings file with the default configuration, which is the file a distribution package or a manual install ends up copying. There is the main header for the extension, plus a stub file describing the PHP side of the API and an argument-information header that the extension build generates or consumes, which is the standard three-file arrangement for exposing functions and classes to the engine.

Then there are two package manifests in two ecosystems: one in the older PHP package format and one in the Composer format. Both are needed because both installation paths still exist, and the manifest for the older format is also what a distribution packager reads.

The credits file and the release process document sit alongside them, and a contributing guide is written in reStructuredText, matching the README, which is itself reStructuredText rather than Markdown. That choice is visible throughout the file: the badges are image directives with link targets underneath them, and the headings are underlined rather than prefixed.

It is an old convention in a codebase that has kept updating, which is a mild curiosity rather than a problem.

Running the tests needs a debug-enabled build and a switch for OpCache

The testing section is unusually concrete about its preconditions, which is helpful because the suite is not self-hosting.

Three things are required: you need to be comfortable compiling a PHP extension from source, you need a local checkout of the repository, and you need to have compiled the extension in that directory by following the source installation instructions. Then the suite is one command:

bash
php run-xdebug-tests.php

The framework additionally requires that the PHP binary on the path has Xdebug loaded, with remote debugging enabled through `xdebug.mode=debug`. So the tests test a debug-enabled build, which is a stricter requirement than most extension suites impose.

Three escape hatches exist for people running them in constrained environments. Remote debugging tests can be skipped by exporting a variable:

bash
SKIP_DBGP_TESTS=1

A second variable skips tests that cannot run in parallel, and a third skips slow tests. A fourth variable, named after the bytecode cache, takes the values yes or no and controls whether the framework enables or disables it.

That last one is the detail to know about. The same process is being tested with and without an opcode cache, which is how the extension's interaction with it gets covered.

The bug tracker is not the code host, and contributing starts with a message

Two structural facts about this project are worth knowing before you file anything or offer a patch.

The first is that the bug tracker is a separate site from the code. Bug reports go to the project's own tracker at bugs.xdebug.org, while pull requests live on the forge the repository is hosted on. The activity badges at the top of the file point at the forge, not the tracker, so the two are easy to confuse from the outside. Filing on the tracker requires creating an account, and the stated reason is that you can be contacted for more information and to keep out spam.

The second is the barrier to contributing. The extension is written in C, and the file says extensive knowledge of PHP's internals is necessary to contribute at all. It also asks you to reach out before you begin, by email, through an issue, or preferably on IRC on a named network and channel.

That last point is where a project of this age shows: the preferred contact channel is a chat network rather than the forge where the code lives, and the email address belongs to the maintainer, who signs the file at the bottom.

For anything that is not a bug or a patch, the file points at the question and answer site with a tag, as a first stop.

A custom license, deliberately not OSI-approved

The licensing section is the one that will surprise an automated check.

The extension is released under a license of its own, named after the project, which is based on the PHP license. The file then says something most projects would leave unsaid: it is an open source license, though not explicitly endorsed by the Open Source Initiative.

Meanwhile the repository's recorded licence identifier on the forge is empty, because no standard identifier matches a custom file. Both facts are consistent with each other, and both are invisible to any tool that reads metadata alone.

What that means practically is that a licence scanner will report the project as unlicensed rather than as permissively licensed, and an organisation with an approved-licence list will have to make a decision by reading the file. There is a licence file at the root, so the terms are available; they are simply not in a form a machine recognises.

On the release state: the newest stable release is 3.5.3 from June 2026, there is a prerelease of 3.6.0 from September 2026, and the release list skips a number between 3.5.1 and 3.5.3. The default branch was pushed on 1 October 2026, after the prerelease. The file also carries a political badge and a block of third-party repository analytics, both generated from an external service.

Editorial conclusion

Xdebug is the default answer for stepping through PHP, and its design explains why it is also the usual suspect when a site feels slow: features are opt-in individually, so the only reliable way to know what is running is the setting list, and the file points to a documentation set with over a hundred settings rather than pretending the defaults are self-evident. Three things to check. Installation is either your distribution's package or the pie installer, and which one you used changes how you upgrade. The test suite is not a quick check, since it needs a debug-enabled build and its harness toggles OpCache, so budget for a compile before trusting a green run. And the licence is a custom file derived from the PHP licence that the project itself notes is not OSI-approved, which matters if your organisation checks licence identifiers automatically.

Frequently asked questions

What does Xdebug provide for PHP developers?

Step debugging plus a range of development helpers: stack traces, a code profiler, and the ability to dump the full execution of a script to a file.

What does Xdebug require before you can install it?

A supported version of PHP, and the pie installer tool, unless your Linux distribution already ships an Xdebug package, most often named php-xdebug. The pie route works on Linux, macOS and Windows through pie install xdebug/xdebug.

How is Xdebug's step debugger turned on?

Each feature has its own opt-in. For the step debugger you set xdebug.remote_enable=1 in your configuration file, and you also need an IDE acting as the client that receives the connection.

How do I run Xdebug's own test suite?

Compile the extension in a local checkout following the source installation instructions, then run php run-xdebug-tests.php. The framework needs the PHP binary on the path to have Xdebug loaded with remote debugging enabled through xdebug.mode=debug, and three environment variables skip remote debugging, unparallel and slow tests.

What license is Xdebug released under?

The Xdebug License, which is based on The PHP License. The file calls it an open source license though not explicitly endorsed by the Open Source Initiative, and the forge records no recognised licence identifier for the repository, although a licence file exists at its root.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. xdebug/xdebug on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/xdebug-xdebug.svg)](https://hysenlabs.com/projects/xdebug-xdebug)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/xdebug-xdebug.svg)](https://hysenlabs.com/projects/xdebug-xdebug)

Was this useful?