phpenv.fish

A fast, feature-rich PHP version manager for Fish Shell that acts like goenv or nvm.

Features

• Fast version detection (100-1000x faster than brew list)
• Dynamic version resolution from shivammathur/setup-php
• Multiple version sources: .php-version, .tool-version, composer.json
• Auto-installation of missing PHP versions
• Extension management with availability checking
• Composer.json integration with full semver support
• Auto-switching between versions (configurable)
• Fisher package manager support
• Rich completions with descriptions

Installation

Using Fisher (recommended)

fisher install ivuorinen/phpenv.fish

Manual Installation

1. Copy files to your fish configuration:

   # Functions
   curl -L https://raw.githubusercontent.com/ivuorinen/phpenv.fish/main/functions/phpenv.fish > ~/.config/fish/functions/phpenv.fish
   
   # Completions
   curl -L https://raw.githubusercontent.com/ivuorinen/phpenv.fish/main/completions/phpenv.fish > ~/.config/fish/completions/phpenv.fish
   
   # Configuration
   curl -L https://raw.githubusercontent.com/ivuorinen/phpenv.fish/main/conf.d/phpenv.fish > ~/.config/fish/conf.d/phpenv.fish
   

2. Install dependencies:

   brew install jq
   

3. Add Homebrew taps:

   brew tap shivammathur/php
   brew tap shivammathur/extensions
   

Quick Start

# Show available versions
phpenv versions

# Install PHP versions
phpenv install 8.3
phpenv install 8.1

# Set global default
phpenv global 8.3

# Set project-specific version
phpenv local 8.1

# Install extensions
phpenv extensions install xdebug
phpenv extensions install redis

# Configure behavior
phpenv config set auto-switch false  # Disable auto-switching
phpenv config set auto-install true  # Enable auto-installation

# Check installation
phpenv doctor

Commands

Version Management

• phpenv install <version> - Install PHP version
• phpenv uninstall <version> - Uninstall PHP version
• phpenv use <version> - Use version for current shell
• phpenv local <version> - Set version for current project
• phpenv global <version> - Set global default version
• phpenv list - List installed versions
• phpenv current - Show current version
• phpenv versions - Show all available versions

Extension Management

• phpenv extensions install <ext> - Install extension for current PHP
• phpenv extensions uninstall <ext> - Uninstall extension
• phpenv extensions list - List installed extensions
• phpenv extensions available - Show available extensions

Configuration

• phpenv config get <key> - Get configuration value
• phpenv config set <key> <value> - Set configuration value
• phpenv config list - List all configuration

Utilities

• phpenv which [binary] - Show path to PHP binary
• phpenv doctor - Check installation health
• phpenv help - Show help

Version Detection

phpenv automatically detects PHP versions from multiple sources (in priority order):

1. .php-version - Project-specific version file
2. .tool-version - Tool version file (parses v8.4 as 8.4)
3. composer.json - Both config.platform.php and require.php with semver support
4. Global version - Fish universal variable
5. System PHP - Fallback to system installation

Composer.json Support

Supports all semver constraints:

• ^8.1 → Uses PHP 8.3 (latest 8.x)
• ~8.2.0 → Uses PHP 8.2
• >=8.0 → Uses PHP 8.3
• 8.1.* → Uses PHP 8.1

Checks both locations:

{
  "require": {
    "php": "^8.1"
  },
  "config": {
    "platform": {
      "php": "8.2.0"
    }
  }
}

Configuration

Configuration Keys

• auto-install - Auto-install missing versions (default: false)
• auto-install-extensions - Install extensions with new PHP versions (default: false)
• auto-switch - Auto-switch versions when changing directories (default: true)
• default-extensions - Space-separated list of default extensions (default: "opcache")
• global-version - Global PHP version

Configuration Files

phpenv checks these locations (in order):

1. ~/.config/fish/conf.d/phpenv.fish (preferred)
2. ~/.config/phpenv/config
3. ~/.phpenv.fish

Examples

# Enable auto-installation
phpenv config set auto-install true

# Disable auto-switching
phpenv config set auto-switch false

# Set default extensions
phpenv config set default-extensions "opcache xdebug redis"

# Enable auto-extension installation
phpenv config set auto-install-extensions true

Supported PHP Versions

Uses shivammathur/homebrew-php with dynamic version detection:

Version Aliases:

• latest - Latest stable PHP version
• nightly - Development version
• 8.x - Latest PHP 8.x version
• 7.x - Latest PHP 7.x version
• 5.x - Latest PHP 5.x version

Available Versions: 5.6, 7.0-7.4, 8.0-8.5

Supported Extensions

Uses shivammathur/homebrew-extensions:

• xdebug, redis, imagick, mongodb, memcached
• pcov, ast, grpc, protobuf, yaml
• And many more...

Performance

• Directory checks: ~1-5ms (vs ~1000ms for brew list)
• Bulk version detection: ~10ms for all versions
• No Ruby overhead or git operations
• Efficient caching and lazy loading

Auto-switching

phpenv automatically switches PHP versions when you change directories if a version file is detected in the project.

Fisher Integration

Works seamlessly with Fisher package manager:

# Install
fisher install ivuorinen/phpenv.fish

# Update
fisher update ivuorinen/phpenv.fish

# Uninstall
fisher remove ivuorinen/phpenv.fish

Troubleshooting

Check Installation

phpenv doctor

Common Issues

jq not found

brew install jq

PHP version not found

# Add taps manually
brew tap shivammathur/php
brew tap shivammathur/extensions

# Install specific version
phpenv install 8.3

Slow performance

• phpenv is designed to be fast by avoiding brew list
• If performance issues persist, check your filesystem or try phpenv doctor

Debug Information

# Check current detection
phpenv current

# Check which binary is used
phpenv which php

# List all configuration
phpenv config list

Contributing

Contributions welcome! Please see CONTRIBUTING.md for detailed guidelines.

Quick Guidelines:

1. Follow fish shell best practices
2. Add tests for new functionality
3. Update documentation
4. Maintain performance optimizations
5. Run pre-commit hooks before submitting

Development Setup:

# Link development version to Fish config
ln -sf $PWD/functions/phpenv.fish ~/.config/fish/functions/phpenv.fish
ln -sf $PWD/completions/phpenv.fish ~/.config/fish/completions/phpenv.fish
ln -sf $PWD/conf.d/phpenv.fish ~/.config/fish/conf.d/phpenv.fish

# Install pre-commit hooks
pip install pre-commit
pre-commit install

Performance Optimizations

phpenv.fish is designed for speed and efficiency:

Caching System

• API Data Caching: Version information cached for 5 minutes
• Homebrew Path Caching: Cellar path permanently cached
• Smart Debouncing: Auto-switching limited to prevent excessive PATH changes

Unified Helper Functions

• Consolidated jq Parsing: Single function eliminates repeated API calls
• Unified Tap Management: Shared logic for Homebrew tap operations
• Optimized Formula Listing: Cached and shared across operations

Performance Metrics

• 100-1000x faster than brew list for version detection
• Direct directory checks instead of subprocess calls
• Minimal network requests with intelligent caching

License

MIT License - see LICENSE file for details.

Related Projects

• shivammathur/homebrew-php
• shivammathur/homebrew-extensions
• jorgebucaran/fisher