Documentation

[01/14] Getting started

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.

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

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:

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

[02/14] Installing versions

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.

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

[03/14] Switching versions

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.

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:

echo "7.2" > .php-version

[04/14] Extensions

Extension management

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

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

[05/14] PHAR tools

PHAR tools

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

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

[06/14] PECL

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.

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

[07/14] Bundles

Portable bundles

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

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

[08/14] Doctor

phpv doctor

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

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

[09/14] Configuration

Configuration

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

phpv config

[10/14] Completions & update

Completions & self-update

Generate shell completion and self-update phpv:

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

[11/14] Uninstall

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

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

[12/14] Version support

Supported PHP versions

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.

[13/14] Troubleshooting

Troubleshooting

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

phpv install 8.4 --fresh --verbose

[14/14] License

License

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