# 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.