diff --git a/docs/getting-started/docker.mdx b/docs/getting-started/docker.mdx index 21d7090..a568c1a 100644 --- a/docs/getting-started/docker.mdx +++ b/docs/getting-started/docker.mdx @@ -161,6 +161,6 @@ image that already has the debugger in it. ## Next steps -- [More install options](./install-options.md) — prebuilt binaries, package - managers, and building from source +- [More install options](./install-options/index.md) — PIE, prebuilt binaries, + and building from source - [Configuration](./configuration.md) — the settings you can change diff --git a/docs/getting-started/install-options.md b/docs/getting-started/install-options.md deleted file mode 100644 index 0f56d28..0000000 --- a/docs/getting-started/install-options.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: More install options ---- - -Ways to install PHP Debugger beyond the installer — prebuilt binaries, package -managers, and building from source. - -:::note -This page is a work in progress — full documentation is coming soon. -::: - -For the recommended route, see [Installation](./installation.mdx). diff --git a/docs/getting-started/install-options/binaries.mdx b/docs/getting-started/install-options/binaries.mdx new file mode 100644 index 0000000..4cba799 --- /dev/null +++ b/docs/getting-started/install-options/binaries.mdx @@ -0,0 +1,106 @@ +--- +title: Prebuilt binaries +--- + +import ConsoleSample from '@site/src/components/ConsoleSample'; + +Every release ships ready-built binaries on the +[Releases page](https://github.com/php-debugger/php-debugger/releases): a complete +PHP **interpreter** with the debugger compiled in, and the **extension** on its own. +Nothing is compiled on your machine, and no installer is involved — you download a +file and put it somewhere. + +The catch is that you pick the right file yourself. Get it wrong and PHP either +refuses to load the extension or fails to start. + +## Work out what you need + +Three things have to match your PHP: the **minor version**, the **thread safety**, +and your **platform**. + +```bash +php -v # 8.4.x -> you want the php8.4 files +php -i | grep "Thread Safety" # disabled -> nts, enabled -> ts +php-config --extension-dir # where the extension has to go +``` + +`Thread Safety => disabled` means you want the `nts` files, which is what a normal +CLI or PHP-FPM build is. `enabled` means `ts`. + +## File names + +Builds are published for PHP 8.2 to 8.5, thread-safe and not, on Linux, macOS and +Windows, for both `arm64` and `x86_64`: + +| What | File | +| --- | --- | +| Interpreter | `php-php8.4-nts-linux-arm64` | +| Interpreter (Windows) | `php-php8.4-nts-windows-x64.exe` | +| Extension | `php-debugger-php8.4-nts-linux-arm64.so` | +| Extension (Windows) | `php_php-debugger-php8.4-nts-windows-x64.dll` | + +Swap `8.4` for your PHP version, `nts` for `ts` if your build is thread-safe, and +the platform for yours — `linux`, `macos` or `windows`, with `arm64` or `x86_64` +(`x64` on Windows). + +## The interpreter + +A single self-contained file. Download it, make it executable, and run it: + +```bash +curl -fsSL -o php-debugger \ + https://github.com/php-debugger/php-debugger/releases/latest/download/php-php8.4-nts-linux-arm64 +chmod +x php-debugger +./php-debugger -v +``` + +{`PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS) +Copyright (c) The PHP Group +Zend Engine v4.4.23, Copyright (c) Zend Technologies + with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`} + +Put it on your PATH if you want it to be the `php` you run. Nothing needs +enabling — the debugger is compiled in, debugging is on by default, and every +request starts a session. + +## The extension + +Download the `.so` into your extension directory, then load it from `php.ini`: + +```bash +curl -fsSL -o "$(php-config --extension-dir)/php_debugger.so" \ + https://github.com/php-debugger/php-debugger/releases/latest/download/php-debugger-php8.4-nts-linux-arm64.so +``` + +```ini +zend_extension=php_debugger.so +``` + +It must be `zend_extension`, not `extension` — the debugger hooks into the engine +and has to be registered as a Zend extension. Check it loaded: + +{`$ php -v +... + with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`} + +If PHP starts but the debugger is missing, or you get a "Zend Extension build ID" +mismatch, the file does not match your PHP — check the version and thread safety +again. + +:::note[On macOS] + +A file downloaded through a **browser** is quarantined, and Gatekeeper will refuse +to run it. Downloading with `curl` as shown avoids that. If you did use a browser, +clear the flag once: + +```bash +xattr -d com.apple.quarantine ./php-debugger +``` + +::: + +## Staying up to date + +There is nothing to update these for you — download the newer file and replace the +old one. The [installer](../installation.mdx) does this with `php-debugger update` +if you would rather not track releases yourself. diff --git a/docs/getting-started/install-options/from-source.mdx b/docs/getting-started/install-options/from-source.mdx new file mode 100644 index 0000000..2dc9db8 --- /dev/null +++ b/docs/getting-started/install-options/from-source.mdx @@ -0,0 +1,99 @@ +--- +title: Building from source +--- + +import ConsoleSample from '@site/src/components/ConsoleSample'; + +:::warning[Try something else first] + +Every other option on this page gives you a build that has already been tested on +the platform you are running. Building from source is the right answer when +nothing else covers your platform, or when you are changing the debugger's code — +not as a default. + +::: + +You can build either the **extension** on its own, which is the ordinary case, or a +complete **PHP interpreter** with the debugger compiled into it. + +This page covers Linux and macOS. Windows uses a different toolchain and has its +own page: [Building on Windows](./windows.mdx). + +Requires PHP 8.2 to 8.5. The build refuses to configure outside that range. + +## The extension + +You need PHP's development headers and a build toolchain: a compiler, `make`, +`autoconf` and `libtool`. On Debian and Ubuntu that is `build-essential`, +`autoconf`, `libtool` and `php-dev`; on Alpine you also need `linux-headers`, +because the build uses `linux/rtnetlink.h`. + +```bash +git clone https://github.com/php-debugger/php-debugger.git +cd php-debugger + +phpize +./configure --enable-php-debugger +make -j$(nproc) +``` + +That leaves `modules/php_debugger.so`. Try it without installing anything: + +```bash +php -d zend_extension=$PWD/modules/php_debugger.so -v +``` + +{`PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS) +Copyright (c) The PHP Group +Zend Engine v4.4.23, Copyright (c) Zend Technologies + with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies + with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`} + +To keep it, copy the file into your extension directory and load it from +`php.ini`: + +```bash +cp modules/php_debugger.so "$(php-config --extension-dir)/" +``` + +```ini +zend_extension=php_debugger.so +``` + +Always `zend_extension`, never `extension` — the debugger hooks into the engine +and has to be registered as a Zend extension. + +`phpize` uses whichever PHP is first on your PATH. If you have several installed, +point the build at the right one with `./configure --with-php-config=/path/to/php-config`. + +## The interpreter + +Building PHP itself with the debugger linked in is what the prebuilt interpreter +binaries and the Docker images are. You compile it as part of PHP rather than +against it: + +```bash +git clone --depth=1 --branch=PHP-8.4 https://github.com/php/php-src.git +git clone https://github.com/php-debugger/php-debugger.git + +cp -r php-debugger php-src/ext/php_debugger +mkdir -p php-src/m4 && cp php-debugger/m4/*.m4 php-src/m4/ + +cd php-src +./buildconf --force +./configure --enable-php-debugger # plus whatever else you need +make -j$(nproc) +``` + +The result is `sapi/cli/php`, with the debugger reported by `php -v` and no +extension to enable. The `./configure` line above is the minimum; a PHP you intend +to actually use will want the usual complement of extensions and SAPIs. + +## If the build fails + +- **`not supported. Need a PHP version >= 8.0.0 and < 8.7.0`** — `phpize` picked up + a PHP outside the supported range. Check `php-config --version`. +- **`rtnetlink.h` not found** — install your distribution's kernel headers + (`apk add linux-headers` on Alpine). +- **PHP starts without the debugger** — you loaded it with `extension=` instead of + `zend_extension=`. diff --git a/docs/getting-started/install-options/index.md b/docs/getting-started/install-options/index.md new file mode 100644 index 0000000..7febe5e --- /dev/null +++ b/docs/getting-started/install-options/index.md @@ -0,0 +1,40 @@ +--- +title: More install options +--- + +There is more than one way to get PHP Debugger onto a machine. They differ in how +much work they are and in what you end up with — either a **self-contained PHP +interpreter** with the debugger compiled in, or the **extension** loaded into a +PHP you already have. + +If you have no particular reason to choose, use the [installer](../installation.mdx). + +| Option | Installs | Good for | +| --- | --- | --- | +| **[Installer](../installation.mdx)** | Either | Almost everyone. One command, and it can undo itself. | +| **[Docker](../docker.mdx)** | Either | Containerised projects. | +| **[PIE](./pie.mdx)** | Extension | Keeping the PHP you have, managed by a standard tool. | +| **[Prebuilt binaries](./binaries.mdx)** | Either | No build tools, no installer — just a file to download. | +| **[From source](./from-source.mdx)** | Either | A platform nothing else covers, or local changes to the code. | +| **[From source on Windows](./windows.mdx)** | Either | The same, on Windows, where the toolchain differs. | + +## Which one gives me what + +The **interpreter** is a complete PHP with the debugger built into it. Nothing to +enable, and it cannot be accidentally unloaded. The trade-off is that it replaces +the `php` you run. + +The **extension** leaves your existing PHP in place and loads the debugger into +it. That keeps whatever else you had configured, at the cost of a `zend_extension` +line and matching a build to your exact PHP. + +## Notes before you pick + +- **Building from source is a last resort.** Every other option gives you a tested + build. Reach for it when nothing else covers your platform, or when you are + changing the code. +- **The extension has to match your PHP exactly** — same minor version, same thread + safety, same architecture. The installer and PIE work that out for you; with + prebuilt binaries you match it yourself. +- **Only the installer knows how to undo itself.** It backs up what it replaced and + restores it on `uninstall`. The other routes leave you to reverse them by hand. diff --git a/docs/getting-started/install-options/pie.mdx b/docs/getting-started/install-options/pie.mdx new file mode 100644 index 0000000..ef92d14 --- /dev/null +++ b/docs/getting-started/install-options/pie.mdx @@ -0,0 +1,66 @@ +--- +title: PIE +--- + +import ConsoleSample from '@site/src/components/ConsoleSample'; + +[PIE](https://github.com/php/pie) — the PHP Installer for Extensions, from the PHP +Foundation — is the standard way to install PHP extensions. It compiles the +debugger against the PHP you already have and enables it for you. + +This installs the **extension**, not the interpreter. Your existing PHP stays +exactly where it is. + +## Before you start + +PIE builds the extension on your machine, so you need a working build toolchain: +a compiler, `make`, `autoconf`, `libtool`, and `unzip`. Most systems used for +development already have these. + +## 1. Get PIE + +Skip this if you already have it. Full instructions are in the +[PIE documentation](https://github.com/php/pie#installation); the short version is +to download the phar and put it on your PATH: + +```bash +curl -fsSL https://github.com/php/pie/releases/latest/download/pie.phar \ + -o /usr/local/bin/pie +chmod +x /usr/local/bin/pie +``` + +## 2. Install the debugger + +```bash +pie install php-debugger/php-debugger +``` + +PIE resolves the latest release, compiles it against your PHP, installs the +resulting `php_debugger.so` into your extension directory, and enables it. If +build tools are missing it will tell you which ones, and `--auto-install-build-tools` +lets it install them for you. + +## 3. Check it worked + +{`$ php -v +PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS) +Copyright (c) The PHP Group +Zend Engine v4.4.23, Copyright (c) Zend Technologies + with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies + with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`} + +The defaults need no configuration: debugging is on, every request starts a +session, and the debugger connects on port 9003 whenever your IDE is listening. + +## Updating and removing + +`pie install` again to move to a newer release. To remove the extension, delete +the `.ini` file PIE wrote and the `php_debugger.so` it installed — +`php --ini` and `php-config --extension-dir` will tell you where both live. + +:::note[Want something that undoes itself?] + +The [installer](../installation.mdx) backs up whatever it replaces and restores it +on `php-debugger uninstall`, which PIE does not do. + +::: diff --git a/docs/getting-started/install-options/windows.mdx b/docs/getting-started/install-options/windows.mdx new file mode 100644 index 0000000..b0aec15 --- /dev/null +++ b/docs/getting-started/install-options/windows.mdx @@ -0,0 +1,127 @@ +--- +title: Building on Windows +--- + +Windows builds PHP and its extensions with Visual Studio and the PHP SDK rather +than `phpize` and `make`, so the process is different enough to be worth its own +page. The debugger-specific part is the same everywhere: a +`--enable-php-debugger` flag. + +As on other platforms, [building from source](./from-source.mdx) is a last resort. +Every release ships [prebuilt Windows binaries](./binaries.mdx) — both the DLL and +a complete `php.exe` — and they are built exactly the way this page describes. + +## What you need + +- **[PHP SDK binary tools](https://github.com/php/php-sdk-binary-tools)** — the + build environment, cloned from GitHub. +- **Visual Studio with the C++ build tools.** Releases are built with VS 2022, + which the SDK calls `vs17`. +- For an extension build, a **development pack** matching your PHP from + [windows.php.net](https://windows.php.net/download/). + +PHP's [step-by-step build guide](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2) +covers getting the SDK set up in more detail than makes sense to repeat here. + +Everything below runs inside an SDK shell. You get one by running the starter +script with the compiler and architecture you are targeting, which sets up the +Visual Studio environment for the commands that follow: + +```batch +git clone https://github.com/php/php-sdk-binary-tools.git C:\php-sdk +C:\php-sdk\phpsdk-vs17-x64.bat +``` + +## The extension + +With a development pack in place, the flow mirrors the one on Linux and macOS: + +```batch +phpize +configure --enable-php-debugger +nmake +``` + +The build produces `php_php_debugger.dll`. Copy it into your `ext` directory and +load it from `php.ini`: + +```ini +zend_extension=php_php_debugger.dll +``` + +It must be `zend_extension`, not `extension` — the debugger hooks into the engine +and has to be registered as a Zend extension. + +:::tip[Building DLLs in CI] + +If you are producing DLLs automatically rather than on a desktop, the +[php-windows-builder](https://github.com/php/php-windows-builder) action does the +whole job, and is what this project's own release builds use. Pass +`--enable-php-debugger` as its `args`. + +::: + +## The interpreter + +To build a `php.exe` with the debugger compiled in, you build PHP itself with the +extension sitting inside its source tree. + +**1. Set up a build tree.** The SDK wants a specific directory layout: + +```batch +git clone https://github.com/php/php-sdk-binary-tools.git C:\php-sdk +C:\php-sdk\bin\phpsdk_buildtree.bat phpdev vs17 x64 +``` + +**2. Clone PHP into it, and copy the debugger into `ext`.** Use the tag for the +PHP version you want: + +```batch +git clone --depth=1 --branch=php-8.4.23 https://github.com/php/php-src.git ^ + C:\php-sdk\phpdev\vs17\x64\php-src +git clone https://github.com/php-debugger/php-debugger.git ext-src +xcopy /E /I /Y ext-src C:\php-sdk\phpdev\vs17\x64\php-src\ext\php_debugger +``` + +**3. Write a build script.** The build has to run inside the SDK shell, so put the +steps in a batch file and hand that to the starter script rather than typing them +interactively: + +```batch +cd /d C:\php-sdk\phpdev\vs17\x64\php-src +call buildconf.bat --force +call configure.bat --enable-php-debugger --disable-opcache-jit +nmake +``` + +`--disable-opcache-jit` matters: the JIT compiler is incompatible with the +debugger's engine hooks. Release builds also add the usual complement of +extensions — `--enable-mbstring`, `--enable-mysqlnd`, `--with-curl`, +`--with-openssl` and so on — and pass `--enable-zts` for a thread-safe build. + +**4. Run it through the SDK.** + +```batch +C:\php-sdk\phpsdk-starter.bat -c vs17 -a x64 -t C:\php-sdk\phpdev\vs17\x64\php-src\build.bat +``` + +**5. Find the result.** It lands under the build directory, in `Release` for a +non-thread-safe build or `Release_TS` for a thread-safe one: + +```batch +C:\php-sdk\phpdev\vs17\x64\php-src\x64\Release\php.exe -v +``` + +The debugger appears in `php -v` and in `php -m`, with nothing to enable. + +## If the build fails + +- **`configure.bat` is not recognised** — you are not in an SDK shell. Start one + with `phpsdk-vs17-x64.bat`, or run your build script through + `phpsdk-starter.bat`. +- **`php.exe` is not where you expected** — check both `x64\Release` and + `Release`, and the `_TS` variants if you built thread-safe. +- **The DLL will not load** — it has to match your PHP on minor version, thread + safety, architecture, and Visual Studio version. All four. +- **PHP starts without the debugger** — you loaded it with `extension=` instead of + `zend_extension=`. diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 1227540..3182253 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -93,7 +93,7 @@ latest version. :::info[Prefer to install some other way?] -See [More install options](./install-options.md). +See [More install options](./install-options/index.md). ::: diff --git a/sidebars.js b/sidebars.js index adb8c64..90ad159 100644 --- a/sidebars.js +++ b/sidebars.js @@ -13,7 +13,17 @@ const sidebars = { 'getting-started/introduction', 'getting-started/installation', 'getting-started/docker', - 'getting-started/install-options', + { + type: 'category', + label: 'More install options', + link: {type: 'doc', id: 'getting-started/install-options/index'}, + items: [ + 'getting-started/install-options/pie', + 'getting-started/install-options/binaries', + 'getting-started/install-options/from-source', + 'getting-started/install-options/windows', + ], + }, 'getting-started/quick-start', 'getting-started/configuration', ],