---
title: phpv
description: Overview, features, how it works.
url: https://phpv.supanadit.com/index.md
---

# phpv

**The PHP version manager that actually compiles · Go**

phpv is a PHP version manager written in Go that resolves the full transitive dependency graph — OpenSSL, libxml2, curl, zlib, oniguruma, ICU — checks what is already on your system, builds what is missing from source, then compiles PHP with the correct --with-* flags. phpv install 8.4 actually works.

- **Status:** v0.14.1
- **License:** MIT
- **Repository:** <https://github.com/supanadit/phpv>

## What it does

Every other major language ships prebuilt binaries. PHP does not. phpv resolves the full transitive dependency graph, reuses what your system already has, builds the rest from source, and compiles PHP with the correct --with-* flags. phpv install 8.4 actually works.

## The problem

PHP is the only major language without prebuilt Linux binaries. Node, Python, Ruby, Go — all ship official binaries. PHP expects you to compile. Compiling PHP by hand means hunting down OpenSSL, libxml2, curl, zlib, oniguruma and ICU. Getting the --with-* flags right for your extensions is a black art. Version managers like phpenv and phpbrew punt: they assume the deps are already there. phpv makes the whole thing deterministic — and it actually works.

## Features

- **Transitive dependency graph** — Resolves the full graph — OpenSSL, libxml2, curl, zlib, oniguruma, ICU — per extension per PHP version. Deterministic resolution for 7.x/8.0/8.1/8.2+ alike.
- **Reuse what you have** — System packages that satisfy the required version constraints are used directly — no source download, no rebuild. Only what is actually missing gets compiled.
- **Correct --with-* flags** — Compiles PHP with the right configure flags for your extension list. 25 default extensions work out of the box.
- **Ephemeral per-shell use** — phpv use 8.3 in terminal A and phpv use 8.4 in terminal B — each shell gets its own version without touching the global default. Requires phpv init.
- **Per-project .php-version** — Drop a .php-version file in a repo and phpv auto-switches on cd. No more remembering which PHP a project needs.
- **Per-version isolation** — Each PHP version gets its own install prefix and phar directory. No conflicts between versions, ever.
- **Extension management** — phpv extension add/remove/list with --auto-deps, --dry-run and --no-system. Recommends distro-specific dev libraries before building.
- **PHAR & PECL tools** — phpv phar install composer|pie|wp-cli|phpunit per version, and phpv pecl install/list/uninstall. Each PHP version keeps its own tools.
- **Portable bundles** — phpv share 8.4 exports a portable tar.gz; phpv install 8.4 --from bundle.tar.gz imports it. Move builds between machines.
- **phpv doctor** — System readiness check plus extension analysis. Reports missing dev-libraries with distro-specific install commands.
- **PHP 5.x → 8.x support** — From PHP 5.0 (experimental) through 8.x, with per-version default extension sets. Auto-bundles OpenSSL 1.1.1w for 7.4.
- **Parallel, visible builds** — phpv install 8.4 --jobs 4 for parallel make. Per-package download progress with completion counts — no frozen spinners.

## How it works

phpv turns "compile PHP from source" into a single deterministic command. It resolves the dependency graph, reuses what your system already has, builds only what is missing, and compiles PHP with the correct flags.

Dependencies are keyed by (name, version) and shared across PHP versions that pin the same version — build once, reuse everywhere. phpv only downloads and extracts what it will actually compile; system packages that satisfy the required version constraints are used directly, and build tools come from the system.


---
title: phpv — Features
description: Deep reference for each phpv capability.
url: https://phpv.supanadit.com/features.md
---

# phpv — Features

phpv is a PHP version manager written in Go that resolves the full transitive dependency graph — OpenSSL, libxml2, curl, zlib, oniguruma, ICU — checks what is already on your system, builds what is missing from source, then compiles PHP with the correct --with-* flags. phpv install 8.4 actually works.

## Feature reference

1. **Transitive dependency graph** — Resolves the full graph — OpenSSL, libxml2, curl, zlib, oniguruma, ICU — per extension per PHP version. Deterministic resolution for 7.x/8.0/8.1/8.2+ alike.
2. **Reuse what you have** — System packages that satisfy the required version constraints are used directly — no source download, no rebuild. Only what is actually missing gets compiled.
3. **Correct --with-* flags** — Compiles PHP with the right configure flags for your extension list. 25 default extensions work out of the box.
4. **Ephemeral per-shell use** — phpv use 8.3 in terminal A and phpv use 8.4 in terminal B — each shell gets its own version without touching the global default. Requires phpv init.
5. **Per-project .php-version** — Drop a .php-version file in a repo and phpv auto-switches on cd. No more remembering which PHP a project needs.
6. **Per-version isolation** — Each PHP version gets its own install prefix and phar directory. No conflicts between versions, ever.
7. **Extension management** — phpv extension add/remove/list with --auto-deps, --dry-run and --no-system. Recommends distro-specific dev libraries before building.
8. **PHAR & PECL tools** — phpv phar install composer|pie|wp-cli|phpunit per version, and phpv pecl install/list/uninstall. Each PHP version keeps its own tools.
9. **Portable bundles** — phpv share 8.4 exports a portable tar.gz; phpv install 8.4 --from bundle.tar.gz imports it. Move builds between machines.
10. **phpv doctor** — System readiness check plus extension analysis. Reports missing dev-libraries with distro-specific install commands.
11. **PHP 5.x → 8.x support** — From PHP 5.0 (experimental) through 8.x, with per-version default extension sets. Auto-bundles OpenSSL 1.1.1w for 7.4.
12. **Parallel, visible builds** — phpv install 8.4 --jobs 4 for parallel make. Per-package download progress with completion counts — no frozen spinners.

## How it works

phpv turns "compile PHP from source" into a single deterministic command. It resolves the dependency graph, reuses what your system already has, builds only what is missing, and compiles PHP with the correct flags.

Dependencies are keyed by (name, version) and shared across PHP versions that pin the same version — build once, reuse everywhere. phpv only downloads and extracts what it will actually compile; system packages that satisfy the required version constraints are used directly, and build tools come from the system.


---
title: phpv — Command Reference
description: The full phpv command surface, grouped by workflow.
url: https://phpv.supanadit.com/commands.md
---

# phpv — Command Reference

The full phpv command surface, grouped by workflow. Every command is a single binary — no runtime dependencies.

## Install & build

| Command | Description |
| --- | --- |
| `phpv install <ver>` | Install a PHP version with default extensions |
| `phpv rebuild <ver>` | Rebuild PHP with different extensions (keeps deps) |
| `phpv uninstall <ver>` | Remove an installed PHP version |
| `phpv share <ver>` | Export PHP as a portable bundle |

## Switching

| Command | Description |
| --- | --- |
| `phpv use <ver>` | Switch for current shell (ephemeral; --global for global) |
| `phpv default <ver>` | Set global default PHP version |
| `phpv versions` | List installed PHP versions |
| `phpv which` | Show path to current PHP binary |

## Extensions

| Command | Description |
| --- | --- |
| `phpv extension list [ver]` | List installed extensions |
| `phpv extension available [ver]` | List extensions available for a version |
| `phpv extension add <name>…` | Install extensions into the active version |
| `phpv extension remove <name>…` | Remove extensions from the active version |

## PHAR & PECL

| Command | Description |
| --- | --- |
| `phpv phar install <name> [ver]` | Install a PHAR tool (composer/pie/wp-cli/phpunit) |
| `phpv phar update <name> [ver]` | Update a PHAR tool |
| `phpv pecl install <name|archive> [ver]` | Install a PECL extension |
| `phpv pecl uninstall <name> [ver]` | Remove a PECL extension |

## System & tools

| Command | Description |
| --- | --- |
| `phpv init <shell>` | Generate shell integration (bash/zsh/fish/pwsh/ksh) |
| `phpv doctor [ver]` | System readiness check + extension analysis |
| `phpv update` | Self-update phpv |
| `phpv completion <shell>` | Generate shell completion |


---
title: phpv — Install & Quickstart
description: One-line installer, release binaries, build from source, quick start.
url: https://phpv.supanadit.com/install.md
---

# phpv — Install & Quickstart

The recommended path is the one-line installer: it detects your platform and shell, installs to $PHPV_ROOT/bin (default ~/.phpv), and wires up shell integration automatically. Prebuilt binaries and building from source are also supported.

Repository: <https://github.com/supanadit/phpv>

## Install script (recommended)

```sh
curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/install.sh | bash
```

## Pin a specific version

```sh
INSTALL_VERSION=0.11.0 curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/install.sh | bash
```

## Download a release binary

### Linux x86_64

```sh
curl -fsSL https://github.com/supanadit/phpv/releases/download/0.14.1/phpv-0.14.1-linux-amd64 -o phpv
chmod +x phpv
sudo mv phpv /usr/local/bin/
phpv --version
```

### Linux arm64

```sh
curl -fsSL https://github.com/supanadit/phpv/releases/download/0.14.1/phpv-0.14.1-linux-arm64 -o phpv
chmod +x phpv
sudo mv phpv /usr/local/bin/
phpv --version
```

### macOS x86_64

```sh
curl -fsSL https://github.com/supanadit/phpv/releases/download/0.14.1/phpv-0.14.1-darwin-amd64 -o phpv
chmod +x phpv
sudo mv phpv /usr/local/bin/
phpv --version
```

### macOS arm64

```sh
curl -fsSL https://github.com/supanadit/phpv/releases/download/0.14.1/phpv-0.14.1-darwin-arm64 -o phpv
chmod +x phpv
sudo mv phpv /usr/local/bin/
phpv --version
```

## Build from source

```sh
git clone https://github.com/supanadit/phpv.git && cd phpv && go build -o phpv ./app/phpv.go
```

## Quick start

```sh
# The installer adds `eval "$(phpv init <shell>)"` to your shell config
# automatically. Restart your shell (or source the config), then:
phpv which          # path to the current PHP binary
phpv versions       # list installed PHP versions
phpv install 8.4    # 25 default extensions, deps auto-resolved
phpv use 8.4 --global
```

## Status & License

Status: v0.14.1

License: MIT — © 2026 Supan Adit Pratama.


---
title: phpv — Documentation
description: Full reference: install and shell init, install flags, switching, extensions, PHAR and PECL, bundles, doctor, config, completions, uninstall, version support, troubleshooting.
url: https://phpv.supanadit.com/docs.md
---

# phpv — Documentation (v0.14.0)

phpv documentation: install and shell init, installing PHP versions with flags, ephemeral per-shell switching and .php-version, extension management, PHAR and PECL tools, portable bundles, doctor, configuration, completions, uninstall, the version support matrix, and troubleshooting.

## Contents

1. [Getting started](#getting-started)
2. [Installing PHP versions](#installing)
3. [Switching versions](#switching)
4. [Extension management](#extensions)
5. [PHAR tools](#phar)
6. [PECL extensions](#pecl)
7. [Portable bundles](#bundles)
8. [phpv doctor](#doctor)
9. [Configuration](#config)
10. [Completions & self-update](#completions)
11. [Uninstall](#uninstall)
12. [Supported PHP versions](#versions)
13. [Troubleshooting](#troubleshooting)
14. [License](#license)

<a id="getting-started"></a>

## 1. Getting started

phpv ships as a single Go binary. The recommended path is the one-line installer, which detects your platform and shell, installs to `$PHPV_ROOT/bin` (default `~/.phpv`), and wires up shell integration automatically.

```sh
# One-line installer (recommended)
curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/install.sh | bash

# Pin a specific version
INSTALL_VERSION=0.11.0 curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/install.sh | bash
```

The installer detects your OS (linux/darwin) and architecture (amd64/arm64), downloads the matching release binary to `$PHPV_ROOT/bin/phpv`, backs up any existing binary, and appends `eval "$(phpv init <shell>)"` to your shell config (`.bashrc`, `.zshrc`, `config.fish`, etc.) if it is not already present.

### Alternative: download a release binary

Prefer a manual install? Download a binary for your platform from the [releases page](https://github.com/supanadit/phpv/releases/latest) — each ships with a matching `.sha256` file. The installer uses the same binaries, so this is only needed if you want to avoid piping curl to bash.

### Alternative: build from source

```sh
git clone https://github.com/supanadit/phpv.git
cd phpv && go build -o phpv ./app/phpv.go
```

### Your first install

After installing, restart your shell (or source the config the installer updated), then:

```sh
phpv which          # path to the current PHP binary
phpv versions       # list installed PHP versions
phpv install 8.4    # 25 default extensions, deps auto-resolved
phpv use 8.4 --global
```

> **Shell integration** — The installer adds the `phpv init` line for you. If you installed a binary manually, add `eval "$(phpv init bash)"` to your shell config yourself — it is required for ephemeral per-shell `phpv use` switching.

<a id="installing"></a>

## 2. Installing PHP versions

`phpv install <ver>` installs a PHP version with the default extension set. Dependencies are resolved from the extension graph and built from source only when your system does not already satisfy the version constraints.

```sh
phpv install 8.4                              # 25 default extensions
phpv install 7.4                              # auto-bundles OpenSSL 1.1.1w
phpv install 8.4 --ext openssl,curl,apcu      # exact list, no defaults
phpv install 8.4 --minimal                    # --disable-all --enable-cli only
phpv install 8.4 --jobs 4                     # parallel make
phpv install 8.4 --fresh                      # clean rebuild, keep cached source
phpv install 8.4 --verbose                    # full build output
```

### Install flags

| Flag | Description |
| --- | --- |
| --ext <list> | Comma-separated extension list (replaces defaults) |
| --minimal | Bare build (--disable-all --enable-cli only) |
| --fresh | Delete prefix, keep cached source |
| --clean | Delete prefix + source + state |
| --force | Force reinstall even if already installed |
| --static | Fully static build |
| --jobs <n> | Parallel make jobs |
| --verbose | Show full build output |
| --auto-deps | Auto-install system dependencies |
| --no-system | Build all deps from source, skip system packages |
| --dry-run | Show what would be done without doing it |
| --from <bundle> | Install from a bundle file |

> **Deterministic resolution** — Dependencies are keyed by (name, version) and shared across PHP versions that pin the same version — build once, reuse everywhere. phpv only downloads and extracts what it will actually compile.

<a id="switching"></a>

## 3. Switching versions

`phpv use` switches the current shell only — it never touches the global default unless you pass `--global`. This requires `phpv init` in your shell config.

```sh
phpv use 8.3                  # current shell only
phpv use system               # stop pinning, fall back to default/system
phpv use 8.3 --global          # global default
phpv use system --global       # use system PHP as the global default
phpv default 8.3              # set global default
phpv versions                 # list installed
phpv which                    # path to current PHP
```

### Per-project .php-version

Drop a `.php-version` file in a repository and phpv auto-switches on `cd`:

```sh
echo "7.2" > .php-version
```

> **Ephemeral by default** — `phpv use 7` in terminal A and `phpv use 8` in terminal B — each shell gets its own version without touching the global default.

<a id="extensions"></a>

## 4. Extension management

`phpv extension` manages extensions for a PHP version. Commands default to the active version; use `--version` to target a specific one.

```sh
phpv extension list                    # installed extensions
phpv extension available 8.4           # available for a version
phpv extension add pdo_pgsql           # into the active version
phpv extension add redis --version 8.4 # into a specific version
phpv extension remove xdebug
phpv extension add redis --auto-deps --dry-run
```

### System dependency detection

System dev-libraries for extensions are checked automatically and recommended before building. For example, `phpv extension add pdo_pgsql` prompts to install `postgresql-libs` (Arch), `libpq-dev` (Debian/Alpine), or `postgresql-devel` (Fedora).

> **Parity with install** — `extension add` supports `--auto-deps`, `--dry-run`, and `--no-system` — full parity with `phpv install` for system dependency management.

<a id="phar"></a>

## 5. PHAR tools

`phpv phar` manages PHAR tools per PHP version — each PHP version keeps its own phars, so there are no conflicts.

```sh
phpv phar install composer              # into the active PHP version
phpv phar install composer --version 8.4
phpv phar install pie                   # install PIE
phpv phar install wp-cli                # install WP-CLI
phpv phar update composer               # update to latest
phpv phar list                          # list for active PHP version
phpv phar which composer                # show phar path
```

<a id="pecl"></a>

## 6. PECL extensions

`phpv pecl` installs and manages PECL extensions. The `--version` flag defaults to the active version; the legacy positional `[version]` is kept for backwards compatibility.

```sh
phpv pecl install /path/to/ext-1.0.0.tgz
phpv pecl install ext --version 8.4
phpv pecl list
phpv pecl uninstall ext
```

<a id="bundles"></a>

## 7. Portable bundles

Export a PHP build as a portable tar.gz and import it on another machine:

```sh
phpv share 8.4                          # export as portable tar.gz bundle
phpv install 8.4 --from bundle.tar.gz   # install from bundle
```

<a id="doctor"></a>

## 8. phpv doctor

`phpv doctor` is a system readiness check plus extension analysis. It reports missing dev-libraries with distro-specific install commands.

```sh
phpv doctor            # system readiness check
phpv doctor 8.4        # extension analysis for PHP 8.4
```

<a id="config"></a>

## 9. Configuration

`phpv config` views and manages configuration. The install root defaults to `$PHPV_ROOT` (`~/.phpv`).

```sh
phpv config
```

<a id="completions"></a>

## 10. Completions & self-update

Generate shell completion and self-update phpv:

```sh
phpv completion bash     # generate shell completion
phpv update              # self-update phpv
phpv rehash              # regenerate all shims
```

<a id="uninstall"></a>

## 11. Uninstall

Remove phpv and its data. This removes the `$PHPV_ROOT` directory (default `~/.phpv`) and the `phpv init` line from your shell config files (`.bashrc`, `.zshrc`, `config.fish`, etc.).

```sh
curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/uninstall.sh | bash

# skip the confirmation prompt
curl -fsSL https://raw.githubusercontent.com/supanadit/phpv/main/uninstall.sh | bash -s -- --yes
```

<a id="versions"></a>

## 12. Supported PHP versions

| PHP | Default extensions | Notes |
| --- | --- | --- |
| 8.x | 25 | Full default set |
| 7.0+ | 25 | Full default set |
| 5.6 | 24 | opcache skipped (requires PHP 7.0+) |
| 5.2–5.5 | 23 | opcache + json skipped |
| 5.0–5.1 | 23 | Same as 5.2 (Experimental) |
| 4.x | 0 | Use --ext to pick extensions (Experimental) |

### Default extensions

`bcmath`, `curl`, `dom`, `fileinfo`, `filter`, `gd`, `iconv`, `intl`, `json`, `mbstring`, `openssl`, `opcache`, `pdo`, `pdo_mysql`, `pdo_sqlite`, `phar`, `session`, `simplexml`, `sqlite3`, `tokenizer`, `xml`, `xmlreader`, `xmlwriter`, `zip`, `zlib`

Use `--minimal` for a bare build (`--disable-all --enable-cli` only), or `--ext` to specify your own list.

<a id="troubleshooting"></a>

## 13. Troubleshooting

Start with `phpv doctor` for a system readiness check and extension analysis. For a clean rebuild:

```sh
phpv install 8.4 --fresh --verbose
```

> **Missing dev-libraries** — If an extension build fails, `phpv doctor` reports the missing dev-libraries with distro-specific install commands (e.g. `postgresql-libs` on Arch, `libpq-dev` on Debian/Alpine, `postgresql-devel` on Fedora).

<a id="license"></a>

## 14. License

phpv is released under the **MIT License**. Copyright (c) 2025 Supan Adit Pratama.