phpenv

Manage multiple PHP versions

TLDR

Install a PHP version globally

$ phpenv install [version]

Refresh shim files for all PHP binaries known to phpenv

$ phpenv rehash

List all installed PHP versions

$ phpenv versions

Display the currently active PHP version

$ phpenv version

Set the global PHP version

$ phpenv global [version]

Set the local PHP version, which overrides the global version

$ phpenv local [version]

Unset the local PHP version

$ phpenv local --unset

SYNOPSIS

phpenv command [arg...]
phpenv [version]

help [--all|-h|-\?]
    Display help for phpenv or specific command

version
    Show current active PHP version

versions [--bare|--short]
    List all installed PHP versions (current marked with *)

install [-l|--list] version
    Install PHP version (uses php-build); -l lists available

uninstall version
    Uninstall specified PHP version

rehash
    Regenerate shims for updated PHP binaries

local [version|--unset]
    Set or unset project-local PHP version (.php-version file)

local-global [version|--unset]
    Set project-local to match global version

global [version|--unset]
    Set or unset user-global PHP version

shell version
    Temporarily activate PHP version in current shell

which command
    Show full path to shim-resolved executable

whence command
    List all PHP versions providing the command

DESCRIPTION

phpenv is a lightweight command-line tool designed to manage multiple PHP versions on Linux and other Unix-like systems. Inspired by rbenv for Ruby, it allows developers to install, switch, and run different PHP versions without conflicts. phpenv works by creating shims — simple executable scripts in $PHPE NV_ROOT/shims that delegate to the selected PHP version's binaries.

When you run php, composer, or other PHP tools, phpenv intercepts the command via your PATH and executes the version specified locally (in .php-version file), globally (in ~/.phpenv/version), or via shell (PHPE NV_VERSION env var). It integrates seamlessly with shells like bash and zsh.

Key benefits include per-project PHP versions, easy upgrades/downgrades, and compatibility with extensions via php-build. Requires php-build for compiling PHP versions from source. Ideal for development environments needing version isolation.

CAVEATS

Requires php-build for installs; modifies PATH (add phpenv init to shell profile); shims may conflict with system PHP; source builds need dev tools like gcc, libxml2-dev.

SHELL INTEGRATION

Run phpenv init & eval output in ~/.bashrc or ~/.zshrc to enable shimming.

EXAMPLE USAGE

phpenv install 8.2.0
phpenv local 8.2.0
php -v # shows 8.2.0

HISTORY

phpenv originated in 2012, created by Jonathan Turner as part of the ENVI ecosystem (rbenv/phpenv/etc.). Maintained on GitHub (phpenv/phpenv), it gained popularity for PHP devs needing multi-version support pre-Docker. php-build (by rkh) provides the installer backend. Actively used in 2023 with PHP 8.x support.