PHP Version Manager (phpvm)

Introduction

phpvm is a lightweight PHP Version Manager that allows you to easily install, switch between, and manage multiple PHP versions via the command line.

Example:

$ phpvm version
phpvm version 1.5.0

PHP Version Manager for macOS and Linux
Author: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Repository: https://github.com/Thavarshan/phpvm

Usage: phpvm help

$ phpvm use 8.2
Switching to PHP 8.2...
Switched to PHP 8.2.
$ php -v
PHP 8.2.10
$ phpvm use 8.1
Switching to PHP 8.1...
Switched to PHP 8.1.
$ php -v
PHP 8.1.13

Features

• Install and manage multiple PHP versions.
• Seamlessly switch between installed PHP versions.
• Auto-switch PHP versions based on project .phpvmrc.
• Supports macOS (via Homebrew) and Linux distributions including WSL.
• Smart repository detection for RHEL/Fedora systems with automatic setup guidance.
• Enhanced error handling with actionable solutions when PHP packages are missing.
• Intelligent package availability checking before attempting installations.
• Enhanced cross-platform compatibility with improved shell support.
• Works with common shells (bash, zsh).
• Comprehensive version commands (phpvm version, phpvm --version, phpvm -v).
• Post-install validation with helpful warnings for missing binaries.
• Enhanced Homebrew integration with better link failure detection.
• Informative, color-coded feedback with timestamps for logs.
• Built-in self-tests for verifying functionality (phpvm test).
• Helper functions for better maintainability and reduced code duplication.

Installation

Install & Update phpvm

To install or update phpvm, run one of the following commands:

curl -o- https://raw.githubusercontent.com/Thavarshan/phpvm/main/install.sh | bash

wget -qO- https://raw.githubusercontent.com/Thavarshan/phpvm/main/install.sh | bash

This script will download and set up phpvm in ~/.phpvm and automatically update your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile) with the following lines:

export PHPVM_DIR="$HOME/.phpvm"
export PATH="$PHPVM_DIR/bin:$PATH"
[ -s "$PHPVM_DIR/phpvm.sh" ] && . "$PHPVM_DIR/phpvm.sh"

Verify Installation

Run the following command:

command -v phpvm

If the installation was successful, it should output the path to phpvm.

Usage

Available Commands

Command	Description
phpvm install <version>	Install a specific PHP version
phpvm use <version>	Switch to a specific PHP version
phpvm current	Display the currently active PHP version
phpvm which [version]	Show the path to PHP binary for a version
phpvm deactivate	Temporarily disable phpvm and restore PATH
phpvm system	Switch to system/Homebrew default PHP
phpvm list or phpvm ls	List all installed PHP versions
phpvm auto	Auto-switch based on .phpvmrc file
phpvm test	Run built-in self-tests
phpvm version	Show version information
phpvm --version	Show version information (alias)
phpvm -v	Show version information (alias)
phpvm help	Show help message

Installing PHP Versions

To install a specific version of PHP:

phpvm install 8.1

Smart Repository Detection: On RHEL/Fedora systems, phpvm automatically detects if PHP packages are available in your current repositories. If not, it provides step-by-step instructions to enable the necessary repositories (like Remi's repository) before installation.

Switching PHP Versions

To switch between installed versions:

phpvm use 8.0

To switch back to the system PHP version (Homebrew default on macOS):

phpvm system

Verify the active version with:

php -v

Checking Current PHP Version

To see which PHP version is currently active:

phpvm current

This will display the active PHP version, "system" (if using system PHP), or "none" (if no PHP is active).

Finding PHP Binary Paths

To find the path to a PHP binary for any version:

# Show path for a specific version
phpvm which 8.2

# Show path for current version
phpvm which

This works across all package managers (Homebrew, apt, dnf, yum, pacman) and is useful for IDE configuration or scripting.

Temporarily Disabling phpvm

To temporarily disable phpvm and restore your original PATH:

phpvm deactivate

This is useful for debugging or when you need to use the system default PHP temporarily. To re-enable phpvm, simply use phpvm use <version> again.

Version Information

To check the phpvm version and get information:

phpvm version
# or
phpvm --version
# or
phpvm -v

Auto-Switching PHP Versions

Create a .phpvmrc file in your project directory to specify the desired PHP version:

echo "8.1" > .phpvmrc

When you navigate to that project directory and run:

phpvm auto

phpvm will automatically detect and switch to the version specified in the .phpvmrc file.

Listing Installed Versions

To list all installed PHP versions:

phpvm list

This will show all installed PHP versions and indicate the currently active one.

Running Self-Tests

phpvm includes built-in self-tests to verify everything is working correctly:

phpvm test

This will run a series of tests on your system to ensure all phpvm functions are working properly.

Exit Codes

phpvm uses specific exit codes for better scripting support:

Exit Code	Meaning
0	Success
1	General error
2	Invalid argument or usage error
3	Version not found (not available)
4	Version not installed locally
5	File or permission error
127	Unknown command

Example usage in scripts:

phpvm use 8.2
if [ $? -eq 0 ]; then
    echo "Successfully switched to PHP 8.2"
else
    echo "Failed to switch PHP version"
fi

Uninstallation

To completely remove phpvm, run:

rm -rf ~/.phpvm

Then remove the following lines from your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):

export PHPVM_DIR="$HOME/.phpvm"
export PATH="$PHPVM_DIR/bin:$PATH"
[ -s "$PHPVM_DIR/phpvm.sh" ] && . "$PHPVM_DIR/phpvm.sh"

Troubleshooting

If you experience issues with phpvm, try the following:

General Issues

• Run phpvm test to verify all functions are working correctly
• Check the phpvm version with phpvm version or phpvm --version
• Ensure your shell profile is sourcing phpvm.sh
• Restart your terminal after installing or updating
• Verify that the required package manager is installed:
  • Homebrew for macOS
  • apt, dnf, yum, or pacman for Linux
• Check for permission issues during the installation or PHP version switching process
• For Linux systems, you may need to use sudo for installation and switching
• On WSL systems, ensure you're using bash shell compatibility
• If you encounter Homebrew link issues on macOS, try manually relinking: brew unlink php@X.Y && brew link --force php@X.Y
• Refer to the Changelog for recent updates and fixes

Repository Setup for RHEL/Fedora Systems

If you encounter "PHP packages not found" errors on RHEL-family distributions, phpvm will automatically provide setup instructions. You can also manually enable the required repositories:

Fedora Systems

# Install Remi's repository
sudo dnf install https://rpms.remirepo.net/fedora/remi-release-$(rpm -E %fedora).rpm

# Enable the repository
sudo dnf config-manager --set-enabled remi

# Enable specific PHP version (example for PHP 8.3)
sudo dnf config-manager --set-enabled remi-php83

RHEL/Rocky/AlmaLinux/CentOS Systems

# Install EPEL repository
sudo dnf install epel-release

# Install Remi's repository
sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %rhel).rpm

# Enable the repositories
sudo dnf config-manager --set-enabled remi
sudo dnf config-manager --set-enabled remi-php83  # for PHP 8.3

Alternative: Use Homebrew on Linux

If you prefer to avoid repository management, you can install Homebrew on Linux:

# Install Homebrew on Linux
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to your shell profile
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
source ~/.bashrc

# Now phpvm will use Homebrew instead of dnf/yum
phpvm install 8.3

Development & Testing

phpvm features comprehensive testing across multiple platforms and scenarios. The project includes extensive GitHub Actions workflows that test every aspect of the script.

Built-in Testing

phpvm includes built-in self-tests that validate all core functionality:

# Run the built-in tests
phpvm test

# Get detailed system information for debugging
phpvm info

The built-in test framework verifies:

• Output and formatting functions
• System detection and OS compatibility
• PHP version installation (mocked)
• Version switching and validation
• Auto-switching based on .phpvmrc
• Input validation and security
• System PHP integration

Comprehensive GitHub Actions Testing

The project features a streamlined CI/CD pipeline with comprehensive testing workflows:

1. Core Testing (.github/workflows/test.yml)

Comprehensive testing workflow including:

• Multi-Distribution Testing: 13 Linux distributions across 4 package managers
  • Ubuntu: 20.04, 22.04, 24.04
  • Debian: 11 (Bullseye), 12 (Bookworm)
  • RHEL/CentOS: Rocky Linux 8 & 9, AlmaLinux 8 & 9, Fedora 38 & 39
  • Arch Linux: Latest
  • Alpine Linux: 3.18, 3.19
• Cross-Platform Testing: Ubuntu and macOS (Intel and Apple Silicon)
• PHP Usage Testing: Installation, version switching, and auto-detection
• Performance Testing: Startup time, concurrent operations, load testing
• Integration Testing: End-to-end workflows, installation simulation, error recovery

2. Security Testing (.github/workflows/security-test.yml)

Specialized security validation including:

• Input validation and injection prevention
• Path traversal protection
• Privilege escalation prevention
• Buffer overflow protection
• File permission security
• Environment variable security
• Symlink attack prevention

3. Release Validation (.github/workflows/release.yml)

Release testing and validation for new versions.

Testing Coverage

The testing suite covers:

• All supported Linux distributions with their native package managers
• macOS versions across Intel and Apple Silicon architectures
• WSL environments (Windows Subsystem for Linux)
• Package managers: apt, dnf, yum, pacman, Homebrew, Linuxbrew
• Security scenarios: malicious input, path traversal, privilege escalation
• Performance scenarios: load testing, memory usage, scalability
• Edge cases: corrupted files, permission issues, network failures
• Error recovery: state corruption, missing dependencies

Running Tests Locally

# Run built-in tests
./phpvm.sh test

# Test input validation
./phpvm.sh install "invalid..version"  # Should fail gracefully

# Test system information
./phpvm.sh info

# Test with debug output
DEBUG=true ./phpvm.sh version

Debugging

To enable debug output, set the DEBUG environment variable to true:

DEBUG=true phpvm install 8.1

Maintainers

phpvm is maintained by Jerome Thayananthajothy.

License

This project is licensed under the MIT License. See LICENSE for details.

Disclaimer

phpvm is provided as-is without any warranties. Use it at your own risk.