Skip to content

Commit b5d698c

Browse files
carlos-granadoscarlos-granados
committed
add install options pages
1 parent 1b023fd commit b5d698c

9 files changed

Lines changed: 452 additions & 16 deletions

File tree

‎docs/getting-started/docker.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,6 @@ image that already has the debugger in it.
161161

162162
## Next steps
163163

164-
- [More install options](./install-options.md) — prebuilt binaries, package
165-
managers, and building from source
164+
- [More install options](./install-options/index.md) — PIE, prebuilt binaries,
165+
and building from source
166166
- [Configuration](./configuration.md) — the settings you can change

‎docs/getting-started/install-options.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎docs/getting-started/install-options/binaries.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Prebuilt binaries
3+
---
4+
5+
import ConsoleSample from '@site/src/components/ConsoleSample';
6+
7+
Every release ships ready-built binaries on the
8+
[Releases page](https://github.com/php-debugger/php-debugger/releases): a complete
9+
PHP **interpreter** with the debugger compiled in, and the **extension** on its own.
10+
Nothing is compiled on your machine, and no installer is involved — you download a
11+
file and put it somewhere.
12+
13+
The catch is that you pick the right file yourself. Get it wrong and PHP either
14+
refuses to load the extension or fails to start.
15+
16+
## Work out what you need
17+
18+
Three things have to match your PHP: the **minor version**, the **thread safety**,
19+
and your **platform**.
20+
21+
```bash
22+
php -v # 8.4.x -> you want the php8.4 files
23+
php -i | grep "Thread Safety" # disabled -> nts, enabled -> ts
24+
php-config --extension-dir # where the extension has to go
25+
```
26+
27+
`Thread Safety => disabled` means you want the `nts` files, which is what a normal
28+
CLI or PHP-FPM build is. `enabled` means `ts`.
29+
30+
## File names
31+
32+
Builds are published for PHP 8.2 to 8.5, thread-safe and not, on Linux, macOS and
33+
Windows, for both `arm64` and `x86_64`:
34+
35+
| What | File |
36+
| --- | --- |
37+
| Interpreter | `php-php8.4-nts-linux-arm64` |
38+
| Interpreter (Windows) | `php-php8.4-nts-windows-x64.exe` |
39+
| Extension | `php-debugger-php8.4-nts-linux-arm64.so` |
40+
| Extension (Windows) | `php_php-debugger-php8.4-nts-windows-x64.dll` |
41+
42+
Swap `8.4` for your PHP version, `nts` for `ts` if your build is thread-safe, and
43+
the platform for yours — `linux`, `macos` or `windows`, with `arm64` or `x86_64`
44+
(`x64` on Windows).
45+
46+
## The interpreter
47+
48+
A single self-contained file. Download it, make it executable, and run it:
49+
50+
```bash
51+
curl -fsSL -o php-debugger \
52+
https://github.com/php-debugger/php-debugger/releases/latest/download/php-php8.4-nts-linux-arm64
53+
chmod +x php-debugger
54+
./php-debugger -v
55+
```
56+
57+
<ConsoleSample>{`PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS)
58+
Copyright (c) The PHP Group
59+
Zend Engine v4.4.23, Copyright (c) Zend Technologies
60+
with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
61+
62+
Put it on your PATH if you want it to be the `php` you run. Nothing needs
63+
enabling — the debugger is compiled in, debugging is on by default, and every
64+
request starts a session.
65+
66+
## The extension
67+
68+
Download the `.so` into your extension directory, then load it from `php.ini`:
69+
70+
```bash
71+
curl -fsSL -o "$(php-config --extension-dir)/php_debugger.so" \
72+
https://github.com/php-debugger/php-debugger/releases/latest/download/php-debugger-php8.4-nts-linux-arm64.so
73+
```
74+
75+
```ini
76+
zend_extension=php_debugger.so
77+
```
78+
79+
It must be `zend_extension`, not `extension` — the debugger hooks into the engine
80+
and has to be registered as a Zend extension. Check it loaded:
81+
82+
<ConsoleSample>{`$ php -v
83+
...
84+
with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
85+
86+
If PHP starts but the debugger is missing, or you get a "Zend Extension build ID"
87+
mismatch, the file does not match your PHP — check the version and thread safety
88+
again.
89+
90+
:::note[On macOS]
91+
92+
A file downloaded through a **browser** is quarantined, and Gatekeeper will refuse
93+
to run it. Downloading with `curl` as shown avoids that. If you did use a browser,
94+
clear the flag once:
95+
96+
```bash
97+
xattr -d com.apple.quarantine ./php-debugger
98+
```
99+
100+
:::
101+
102+
## Staying up to date
103+
104+
There is nothing to update these for you — download the newer file and replace the
105+
old one. The [installer](../installation.mdx) does this with `php-debugger update`
106+
if you would rather not track releases yourself.

‎docs/getting-started/install-options/from-source.mdx‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Building from source
3+
---
4+
5+
import ConsoleSample from '@site/src/components/ConsoleSample';
6+
7+
:::warning[Try something else first]
8+
9+
Every other option on this page gives you a build that has already been tested on
10+
the platform you are running. Building from source is the right answer when
11+
nothing else covers your platform, or when you are changing the debugger's code —
12+
not as a default.
13+
14+
:::
15+
16+
You can build either the **extension** on its own, which is the ordinary case, or a
17+
complete **PHP interpreter** with the debugger compiled into it.
18+
19+
This page covers Linux and macOS. Windows uses a different toolchain and has its
20+
own page: [Building on Windows](./windows.mdx).
21+
22+
Requires PHP 8.2 to 8.5. The build refuses to configure outside that range.
23+
24+
## The extension
25+
26+
You need PHP's development headers and a build toolchain: a compiler, `make`,
27+
`autoconf` and `libtool`. On Debian and Ubuntu that is `build-essential`,
28+
`autoconf`, `libtool` and `php-dev`; on Alpine you also need `linux-headers`,
29+
because the build uses `linux/rtnetlink.h`.
30+
31+
```bash
32+
git clone https://github.com/php-debugger/php-debugger.git
33+
cd php-debugger
34+
35+
phpize
36+
./configure --enable-php-debugger
37+
make -j$(nproc)
38+
```
39+
40+
That leaves `modules/php_debugger.so`. Try it without installing anything:
41+
42+
```bash
43+
php -d zend_extension=$PWD/modules/php_debugger.so -v
44+
```
45+
46+
<ConsoleSample>{`PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS)
47+
Copyright (c) The PHP Group
48+
Zend Engine v4.4.23, Copyright (c) Zend Technologies
49+
with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies
50+
with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
51+
52+
To keep it, copy the file into your extension directory and load it from
53+
`php.ini`:
54+
55+
```bash
56+
cp modules/php_debugger.so "$(php-config --extension-dir)/"
57+
```
58+
59+
```ini
60+
zend_extension=php_debugger.so
61+
```
62+
63+
Always `zend_extension`, never `extension` — the debugger hooks into the engine
64+
and has to be registered as a Zend extension.
65+
66+
`phpize` uses whichever PHP is first on your PATH. If you have several installed,
67+
point the build at the right one with `./configure --with-php-config=/path/to/php-config`.
68+
69+
## The interpreter
70+
71+
Building PHP itself with the debugger linked in is what the prebuilt interpreter
72+
binaries and the Docker images are. You compile it as part of PHP rather than
73+
against it:
74+
75+
```bash
76+
git clone --depth=1 --branch=PHP-8.4 https://github.com/php/php-src.git
77+
git clone https://github.com/php-debugger/php-debugger.git
78+
79+
cp -r php-debugger php-src/ext/php_debugger
80+
mkdir -p php-src/m4 && cp php-debugger/m4/*.m4 php-src/m4/
81+
82+
cd php-src
83+
./buildconf --force
84+
./configure --enable-php-debugger # plus whatever else you need
85+
make -j$(nproc)
86+
```
87+
88+
The result is `sapi/cli/php`, with the debugger reported by `php -v` and no
89+
extension to enable. The `./configure` line above is the minimum; a PHP you intend
90+
to actually use will want the usual complement of extensions and SAPIs.
91+
92+
## If the build fails
93+
94+
- **`not supported. Need a PHP version >= 8.0.0 and < 8.7.0`** — `phpize` picked up
95+
a PHP outside the supported range. Check `php-config --version`.
96+
- **`rtnetlink.h` not found** — install your distribution's kernel headers
97+
(`apk add linux-headers` on Alpine).
98+
- **PHP starts without the debugger** — you loaded it with `extension=` instead of
99+
`zend_extension=`.

‎docs/getting-started/install-options/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: More install options
3+
---
4+
5+
There is more than one way to get PHP Debugger onto a machine. They differ in how
6+
much work they are and in what you end up with — either a **self-contained PHP
7+
interpreter** with the debugger compiled in, or the **extension** loaded into a
8+
PHP you already have.
9+
10+
If you have no particular reason to choose, use the [installer](../installation.mdx).
11+
12+
| Option | Installs | Good for |
13+
| --- | --- | --- |
14+
| **[Installer](../installation.mdx)** | Either | Almost everyone. One command, and it can undo itself. |
15+
| **[Docker](../docker.mdx)** | Either | Containerised projects. |
16+
| **[PIE](./pie.mdx)** | Extension | Keeping the PHP you have, managed by a standard tool. |
17+
| **[Prebuilt binaries](./binaries.mdx)** | Either | No build tools, no installer — just a file to download. |
18+
| **[From source](./from-source.mdx)** | Either | A platform nothing else covers, or local changes to the code. |
19+
| **[From source on Windows](./windows.mdx)** | Either | The same, on Windows, where the toolchain differs. |
20+
21+
## Which one gives me what
22+
23+
The **interpreter** is a complete PHP with the debugger built into it. Nothing to
24+
enable, and it cannot be accidentally unloaded. The trade-off is that it replaces
25+
the `php` you run.
26+
27+
The **extension** leaves your existing PHP in place and loads the debugger into
28+
it. That keeps whatever else you had configured, at the cost of a `zend_extension`
29+
line and matching a build to your exact PHP.
30+
31+
## Notes before you pick
32+
33+
- **Building from source is a last resort.** Every other option gives you a tested
34+
build. Reach for it when nothing else covers your platform, or when you are
35+
changing the code.
36+
- **The extension has to match your PHP exactly** — same minor version, same thread
37+
safety, same architecture. The installer and PIE work that out for you; with
38+
prebuilt binaries you match it yourself.
39+
- **Only the installer knows how to undo itself.** It backs up what it replaced and
40+
restores it on `uninstall`. The other routes leave you to reverse them by hand.

‎docs/getting-started/install-options/pie.mdx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: PIE
3+
---
4+
5+
import ConsoleSample from '@site/src/components/ConsoleSample';
6+
7+
[PIE](https://github.com/php/pie) — the PHP Installer for Extensions, from the PHP
8+
Foundation — is the standard way to install PHP extensions. It compiles the
9+
debugger against the PHP you already have and enables it for you.
10+
11+
This installs the **extension**, not the interpreter. Your existing PHP stays
12+
exactly where it is.
13+
14+
## Before you start
15+
16+
PIE builds the extension on your machine, so you need a working build toolchain:
17+
a compiler, `make`, `autoconf`, `libtool`, and `unzip`. Most systems used for
18+
development already have these.
19+
20+
## 1. Get PIE
21+
22+
Skip this if you already have it. Full instructions are in the
23+
[PIE documentation](https://github.com/php/pie#installation); the short version is
24+
to download the phar and put it on your PATH:
25+
26+
```bash
27+
curl -fsSL https://github.com/php/pie/releases/latest/download/pie.phar \
28+
-o /usr/local/bin/pie
29+
chmod +x /usr/local/bin/pie
30+
```
31+
32+
## 2. Install the debugger
33+
34+
```bash
35+
pie install php-debugger/php-debugger
36+
```
37+
38+
PIE resolves the latest release, compiles it against your PHP, installs the
39+
resulting `php_debugger.so` into your extension directory, and enables it. If
40+
build tools are missing it will tell you which ones, and `--auto-install-build-tools`
41+
lets it install them for you.
42+
43+
## 3. Check it worked
44+
45+
<ConsoleSample>{`$ php -v
46+
PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS)
47+
Copyright (c) The PHP Group
48+
Zend Engine v4.4.23, Copyright (c) Zend Technologies
49+
with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies
50+
with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
51+
52+
The defaults need no configuration: debugging is on, every request starts a
53+
session, and the debugger connects on port 9003 whenever your IDE is listening.
54+
55+
## Updating and removing
56+
57+
`pie install` again to move to a newer release. To remove the extension, delete
58+
the `.ini` file PIE wrote and the `php_debugger.so` it installed —
59+
`php --ini` and `php-config --extension-dir` will tell you where both live.
60+
61+
:::note[Want something that undoes itself?]
62+
63+
The [installer](../installation.mdx) backs up whatever it replaces and restores it
64+
on `php-debugger uninstall`, which PIE does not do.
65+
66+
:::

0 commit comments

Comments
 (0)