Language Version Management Tool

phpenv

Overview

phpenv is a simple PHP version management tool based on rbenv. Inheriting rbenv's design philosophy, it manages multiple PHP versions with a lightweight, UNIX-like approach. It allows using different PHP versions per project and supports automatic switching via .php-version files.

Details

Key Features

• rbenv-based: Inherits rbenv's proven design
• Simple mechanism: Transparent version switching using shims
• .php-version files: Automatic version management per project
• php-build plugin: Assists with PHP building and installation
• Lightweight operation: Fast performance with minimal overhead
• Plugin support: Extensible architecture for functionality

How It Works

Like rbenv, phpenv places the ~/.phpenv/shims directory at the beginning of your PATH. When PHP commands are executed, shims determine the appropriate version and redirect to the corresponding PHP executable. Versions are controlled by .php-version files or the PHPENV_VERSION environment variable.

Version Priority

1. PHPENV_VERSION environment variable
2. .php-version file in current directory
3. .php-version file in parent directories (recursive)
4. Global setting (~/.phpenv/version)
5. System PHP

Pros and Cons

Pros

• Simplicity: Zero learning cost for rbenv users
• Lightweight: Fast operation with minimal features
• Transparency: Predictable behavior and easy debugging
• Project isolation: Independent PHP environment for each project
• Version control integration: .php-version manageable with Git
• Customizability: Easy extension through plugins

Cons

• Limited features: Fewer features compared to phpbrew
• Build dependency: php-build plugin is essential
• No Windows support: Only Unix-like OS supported
• rbenv conflicts: Care needed for coexistence with rbenv
• Community: Smaller than phpbrew
• Extension management: Limited extension management features

Reference Pages

• phpenv GitHub Repository
• CHH/phpenv (Original)
• php-build Plugin
• rbenv Official Site

Example Usage

Installation

# Automated installation (recommended)
curl -L https://raw.githubusercontent.com/phpenv/phpenv-installer/master/bin/phpenv-installer | bash

# Manual installation
git clone https://github.com/phpenv/phpenv.git ~/.phpenv

# Install php-build plugin
git clone https://github.com/php-build/php-build.git ~/.phpenv/plugins/php-build

# Shell configuration (add to .bashrc or .zshrc)
echo 'export PATH="$HOME/.phpenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(phpenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Coexistence with rbenv (if using rbenv)
# Prioritize rbenv's PATH
export PATH="$HOME/.rbenv/bin:$HOME/.phpenv/bin:$PATH"

Basic Usage

# Check available PHP versions
phpenv install --list

# Install specific version
phpenv install 8.3.0
phpenv install 8.2.13
phpenv install 7.4.33

# Check installed versions
phpenv versions

# Set global version
phpenv global 8.2.13

# Check current version
phpenv version
php -v

Per-Project Management

# In project directory
cd /path/to/my-project

# Set local version
phpenv local 8.1.26

# .php-version file is created
cat .php-version
# 8.1.26

# Different version in another project
cd /path/to/legacy-project
phpenv local 7.4.33

# Automatic switching on directory change
cd /path/to/my-project
php -v  # PHP 8.1.26
cd /path/to/legacy-project  
php -v  # PHP 7.4.33

Temporary Version Switching

# Valid only in shell session
phpenv shell 8.3.0

# Specify via environment variable
export PHPENV_VERSION=8.3.0

# Unset configuration
phpenv shell --unset
# or
unset PHPENV_VERSION

Installation Options

# Install with default settings
phpenv install 8.2.13

# Custom configure options
PHP_BUILD_CONFIGURE_OPTS="--with-pdo-mysql --with-mysqli" phpenv install 8.2.13

# Multiple options
PHP_BUILD_CONFIGURE_OPTS="--enable-fpm --with-fpm-user=www-data --with-fpm-group=www-data --with-pdo-mysql --with-openssl" phpenv install 8.2.13

# Debug build
PHP_BUILD_CONFIGURE_OPTS="--enable-debug" phpenv install 8.2.13

# Check installation location
ls ~/.phpenv/versions/

Extension Management

# Install extensions for current PHP version
phpenv shell 8.2.13
pecl install redis
pecl install xdebug

# Regenerate shims (important)
phpenv rehash

# Check installed extensions
php -m

# Manage extensions for specific version
cd ~/.phpenv/versions/8.2.13
./bin/pecl install imagick

Commands and Utilities

# Check PHP binary path
phpenv which php
phpenv which composer

# Regenerate shims (recognize new commands)
phpenv rehash

# Delete version
rm -rf ~/.phpenv/versions/7.4.33
phpenv rehash

# Update phpenv itself
cd ~/.phpenv
git pull

# Update php-build
cd ~/.phpenv/plugins/php-build
git pull

Integration with Composer

# Install global Composer
curl -sS https://getcomposer.org/installer | php
mv composer.phar ~/.phpenv/versions/$(phpenv version-name)/bin/composer
phpenv rehash

# Use in project
cd /path/to/project
phpenv local 8.2.13
composer install

# Install Composer for each PHP version
for version in $(phpenv versions --bare); do
  phpenv shell $version
  curl -sS https://getcomposer.org/installer | php
  mv composer.phar ~/.phpenv/versions/$version/bin/composer
done
phpenv rehash

Troubleshooting

# Check build errors
tail -n 50 /tmp/php-build.*.log

# Handle OpenSSL errors (macOS)
brew install openssl
PHP_BUILD_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl)" phpenv install 8.2.13

# Check dependencies (Ubuntu/Debian)
sudo apt-get install -y \
  build-essential \
  libxml2-dev \
  libssl-dev \
  libsqlite3-dev \
  libcurl4-openssl-dev \
  libjpeg-dev \
  libpng-dev \
  libonig-dev \
  libzip-dev

# Resolve shim issues
phpenv rehash
phpenv init -

# Check PATH
echo $PATH | tr ':' '\n' | grep phpenv

CI/CD Environment Usage

# GitHub Actions example
- name: Setup PHP
  run: |
    git clone https://github.com/phpenv/phpenv.git ~/.phpenv
    git clone https://github.com/php-build/php-build.git ~/.phpenv/plugins/php-build
    echo "$HOME/.phpenv/bin" >> $GITHUB_PATH
    eval "$(phpenv init -)"
    phpenv install 8.2.13
    phpenv global 8.2.13

# Travis CI example (.travis.yml)
language: php
php:
  - 8.2
  - 8.1
  - 8.0