How to Make PHP Debugger Available Everywhere

In this document, we list all the possible ways of getting PHP Debugger into the hands of our users and what we need to do to make it available through all relevant channels.

We have two ways of distributing PHP Debugger:

1. The preferred option is to distribute a PHP interpreter with the debugger statically compiled into it.
2. The alternative option is to distribute the debugger as a PHP extension that can be added to an existing PHP installation.

Direct Distribution as Precompiled Binaries

We can build precompiled binaries for both the PHP interpreter and the extension and make them available for download. These binaries should be built for Windows, macOS, and Linux for all relevant architectures.

In addition to providing direct download links, we should also offer a one-line installation command similar to what php.new provides. This command would download either the PHP interpreter or the extension and install it automatically. This would provide the easiest onboarding experience for users who simply want the debugger available on their system.

Building these binaries should be part of the CI pipeline. This is already done for the extension; we would need to add equivalent build steps for the PHP interpreter.

Distribution for Docker

Most professional PHP development today is done using Docker, so we want to make it extremely easy to run containers with PHP Debugger enabled.

If users prefer a PHP interpreter with the debugger statically incorporated, the best approach would be to provide variants of the official PHP Docker images that already include PHP Debugger. This would allow users to replace:

FROM php:8.4-fpm

with:

FROM php-debugger:8.4-fpm

To support this, we would need a process that automatically builds and publishes all supported image variants to Docker Hub.

If users prefer installing the extension separately, they can use PIE. However, installing extensions with PIE inside Docker is currently somewhat cumbersome, and compilation steps slow down container builds.

To improve this experience, we could precompile extension binaries specifically for the official PHP Docker images. CI could build the extension for every supported OS, architecture, and PHP version combination. We could then provide a simple installation command that downloads and installs the correct binary in a single Docker layer.

Distribution Using Package Managers

Many users prefer installing PHP and PHP extensions through their operating system package managers, such as apt, apk, chocolatey, or brew.

Since we will already be building binaries, we mainly need to provide the packaging and repository infrastructure required by each ecosystem.

Debian / Ubuntu (apt)

Initially, we would need to create DEB packages.

We could then:

• Host our own APT repository
• Create a Launchpad PPA
• Provide installation instructions for adding the repository

Once the project gains enough adoption and reputation, we could approach Ondřej Surý to ask whether our packages could be integrated into his widely used PHP repositories.

Fedora / RHEL (rpm)

We would need to:

• Create RPM spec files
• Build RPM packages
• Host an RPM repository

Once the project becomes established, we could approach Remi Collet to explore inclusion in the Remi repositories.

Alpine Linux (apk)

For Alpine support, we would need to:

• Create an APKBUILD
• Build APK packages
• Host an APK repository

Once the project matures, we could attempt to add the package to the official Alpine testing or community aports repositories.

Windows Scoop

For Scoop support, we would need to:

• Create a JSON manifest
• Provide a PowerShell installation script
• Submit the package to the official Scoop bucket

Windows Chocolatey

For Chocolatey support, we would need to:

• Create a .nupkg package
• Provide a PowerShell installation script
• Submit the package to the official Chocolatey repository

macOS Homebrew (brew)

For Homebrew support, we would initially provide our own tap.

Once the project gains enough adoption, we could explore inclusion in the shivammathur/homebrew-extensions repository.

PIE / PECL Installation

Since PECL is being deprecated, we should not invest effort into PECL-based installation flows.

We already provide a PIE installer, so the primary work here is ensuring that the documentation and installation instructions are excellent and easy to follow.

Compiling from Source Manually

Compiling from source should remain a last-resort option intended mainly for:

• Highly specialized installations
• Unsupported systems
• Niche architectures

We should provide:

• Clear documentation
• Dependency requirements
• Example build commands
• Ideally, a one-line bootstrap script that users can copy and run

Through PhpStorm

Currently, PhpStorm allows users to download and install the Xdebug extension directly from the IDE. JetBrains could relatively easily add support for downloading and installing PHP Debugger in a similar way.

Another possible collaboration with JetBrains would be to allow PhpStorm to install and manage PHP interpreters that already include PHP Debugger statically compiled into the binary. This would provide the smoothest possible user experience, as developers could start debugging immediately without having to manually install or configure extensions.

Laravel Herd

Laravel Herd is proprietary software, so integration would likely require collaboration with the maintainers.

Once the project gains sufficient adoption and visibility, we could approach Beyond Code and explore official support.

DDEV

DDEV is a Docker-based development environment that is especially popular with agencies.

If we already provide our own Docker images, using a custom PHP build becomes very easy: users would only need to replace the base image in their DDEV configuration.

For extension-based installation, we could provide a DDEV add-on that automates installation and configuration inside DDEV projects.

WSL2

WSL2 is effectively Linux running under Windows, so all Linux-based distribution methods would work there as well:

• Binary downloads
• APT/APK/RPM repositories
• Docker images
• Source builds

We mainly need to ensure that WSL2 usage is clearly documented so users know which installation methods apply.

Laragon

Laragon supports custom PHP installations and extensions.

If we provide Windows PHP binaries and extension DLLs, users can add them directly to their Laragon installations. We mainly need to provide:

• Clear installation instructions
• Optionally, a command-line installer

XAMPP, WAMP, and MAMP

XAMPP, WAMP, and MAMP used to be extremely popular before Docker became dominant.

They are still relevant because they remain popular among beginner developers and smaller local setups.

Supporting these environments mainly requires:

• Prebuilt binaries
• Extension DLLs/modules
• Clear installation instructions
• Ideally, simple command-line installers

Infrastructure

Initially, most infrastructure can be hosted entirely on GitHub using:

• GitHub Releases
• GitHub Pages
• GitHub Actions

Over time, however, we may want to move to dedicated infrastructure in order to:

• Host repositories more flexibly
• Improve documentation hosting
• Handle higher bandwidth requirements
• Improve release distribution performance

At that point, we would need to determine how the infrastructure will be funded and managed.

We should also purchase a dedicated domain name early on. Initially, it could simply point to GitHub Pages, while later it could be redirected to dedicated infrastructure without changing user-facing URLs.