PHPackages                             rawdreeg/phpswitcher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. rawdreeg/phpswitcher

ActiveProject[CLI & Console](/categories/cli)

rawdreeg/phpswitcher
====================

CLI tool to manage and switch between multiple PHP versions

v0.4.0(3mo ago)206MITShellCI passing

Since Apr 7Pushed 2w ago1 watchersCompare

[ Source](https://github.com/rawdreeg/phpswitcher)[ Packagist](https://packagist.org/packages/rawdreeg/phpswitcher)[ Docs](https://github.com/rawdreeg/phpswitcher)[ RSS](/packages/rawdreeg-phpswitcher/feed)WikiDiscussions develop Synced today

READMEChangelog (8)Dependencies (3)Versions (6)Used By (0)

[![CI](https://github.com/rawdreeg/phpswitcher/actions/workflows/ci.yml/badge.svg)](https://github.com/rawdreeg/phpswitcher/actions/workflows/ci.yml)

PHP Switcher
============

[](#php-switcher)

A simple CLI tool to manage multiple PHP versions on macOS and Linux.

Features
--------

[](#features)

- Install specific PHP versions (via Homebrew for macOS, or APT for Linux).
- Uninstall PHP versions you no longer need.
- Switch the active PHP version.
- List all installed PHP versions.
- Auto-detect required version from `.php-version`, `composer.json`, or global default.
- **Global default version** — set a fallback PHP version used when no project-level config is found.
- **Automatic version switching** when you change directories (supports `.php-version`, `composer.json`, and global default).
- **Status command** — see active PHP version, detection source, and path info at a glance.
- **Extensions management** — list or install PHP extensions for any version.
- **Tab completion** for Bash, Zsh, and Fish.

Prerequisites
-------------

[](#prerequisites)

- **macOS:** Requires **Homebrew** for installing and managing PHP versions.
- **Linux (Debian/Ubuntu):** Requires `apt` and the `software-properties-common` package. `sudo` is required for installing and switching versions.

Installation
------------

[](#installation)

### Homebrew (macOS)

[](#homebrew-macos)

```
brew install rawdreeg/phpswitcher/phpswitcher
```

### Composer

[](#composer)

```
composer global require rawdreeg/phpswitcher
```

### Install script (macOS & Linux)

[](#install-script-macos--linux)

```
bash -c "$(curl -fsSL https://raw.githubusercontent.com/rawdreeg/phpswitcher/main/install.sh)"
```

After installing, restart your terminal and verify with:

```
phpswitcher help
```

Usage
-----

[](#usage)

**List installed PHP versions:**

Shows all available PHP versions and highlights the one that is currently active.

```
phpswitcher list
# Example Output:
#
# Installed PHP Versions (via Homebrew):
#    7.4
#  * 8.1 (active)
```

**Install a PHP version:**

If you are in a directory containing a `composer.json` file with a PHP requirement, you can omit the `` argument to automatically detect and install the required `X.Y` version.

```
phpswitcher install []
# Examples:
phpswitcher install 8.1
phpswitcher install 7.4

# Auto-detect from composer.json in current directory:
cd my-project-using-php8.0/
phpswitcher install
```

**Uninstall a PHP version:**

Remove a PHP version that is no longer needed. The currently active version cannot be uninstalled — switch to a different version first.

```
phpswitcher uninstall
# Example:
phpswitcher uninstall 7.4
```

**Switch active PHP version:**

If you are in a directory containing a `composer.json` file with a PHP requirement (`require.php` or `config.platform.php`), you can omit the `` argument, and `phpswitcher` will attempt to detect and use the appropriate `X.Y` version.

```
phpswitcher use []
# Examples:
phpswitcher use 8.1

# Auto-detect from composer.json in current directory:
cd my-project-using-php7.4/
phpswitcher use
```

**Set a global default PHP version:**

Set a fallback version that's used when no `.php-version` file or `composer.json` is found in the directory tree:

```
phpswitcher default 8.2

# Show the current default:
phpswitcher default

# Remove the default:
phpswitcher default --unset
```

**Show status:**

Display the current active PHP version, how it was detected, and path information:

```
phpswitcher status
# Example Output:
#
# PHP Switcher Status
# ===================
#
# Active PHP version: 8.1
# PHP reports version: 8.1
# PHP binary path:    /usr/bin/php8.1
# Loaded php.ini:     /etc/php/8.1/cli/php.ini
#
# Version detection for current directory:
#   Detected version: 8.1
#   Source:           .php-version (/home/user/project/.php-version)
#
# Global default:     8.2
```

**Manage PHP extensions:**

List installed extensions for a PHP version, or install new ones:

```
# List extensions for the active PHP version:
phpswitcher extensions

# List extensions for a specific version:
phpswitcher extensions 8.1

# Install an extension (uses active version):
phpswitcher extensions install xdebug

# Install an extension for a specific version:
phpswitcher extensions install redis 8.1
```

On Linux, extensions are installed via `apt` (e.g., `php8.1-xdebug`). On macOS, PECL is used.

**Show Version:**

```
phpswitcher version
```

**Self-Update:**

```
phpswitcher self-update
```

This will fetch and install the latest version of `phpswitcher` from GitHub.

**Check active PHP version (after switching):**

```
php --version
```

Automatic Version Switching
---------------------------

[](#automatic-version-switching)

`phpswitcher` supports automatic version switching when you change directories. This is achieved by hooking into your shell's prompt.

### How it Works

[](#how-it-works)

1. When you `cd` into a new directory, `phpswitcher` looks for a `.php-version` file in the current directory or any parent directory.
2. If no `.php-version` file is found, it checks for a `composer.json` in the current directory and reads the PHP version constraint.
3. If neither is found, it falls back to the global default version (if set via `phpswitcher default`).
4. If a required version is detected and it differs from the currently active version, `phpswitcher` automatically switches to it.

### Usage

[](#usage-1)

To use this feature, simply create a file named `.php-version` in the root of your project and put the desired PHP version number in it.

```
# In your project's root directory
echo "8.1" > .php-version
```

Now, whenever you `cd` into this directory (or any subdirectory), `phpswitcher` will ensure that PHP 8.1 is activated automatically.

This feature is enabled by default during the installation process, which adds a sourcing line to your shell's profile file (`.bashrc`, `.zshrc`, or Fish config).

### Fish Shell Support

[](#fish-shell-support)

Fish shell is fully supported. The installer automatically detects Fish and creates a config file at `~/.config/fish/conf.d/phpswitcher.fish`. Auto-switching works via Fish's `--on-variable PWD` event.

Tab Completion
--------------

[](#tab-completion)

Tab completion for commands and PHP versions is enabled automatically during installation for Bash, Zsh, and Fish. Type `phpswitcher` followed by Tab to see available commands, or `phpswitcher use` followed by Tab to see installed PHP versions.

Development
-----------

[](#development)

1. Clone the repository: `git clone https://github.com/rawdreeg/phpswitcher.git`
2. Navigate into the project directory: `cd phpswitcher`.
3. The main script is `bin/phpswitcher`. You can run it directly for testing: ```
    ./bin/phpswitcher install 8.2
    ```
4. To create a release artifact, run the build script: ```
    ./build.sh
    ```

    This will create a `phpswitcher.tar.gz` in the root directory.

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to open issues or submit pull requests.

License
-------

[](#license)

MIT License

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance74

Regular maintenance activity

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 57.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~181 days

Total

3

Last Release

90d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4209011?v=4)[Rodrigue](/maintainers/rawdreeg)[@rawdreeg](https://github.com/rawdreeg)

---

Top Contributors

[![rawdreeg](https://avatars.githubusercontent.com/u/4209011?v=4)](https://github.com/rawdreeg "rawdreeg (53 commits)")[![google-labs-jules[bot]](https://avatars.githubusercontent.com/in/842251?v=4)](https://github.com/google-labs-jules[bot] "google-labs-jules[bot] (24 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (15 commits)")

---

Tags

phpcliversion-manager

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/rawdreeg-phpswitcher/health.svg)

```
[![Health](https://phpackages.com/badges/rawdreeg-phpswitcher/health.svg)](https://phpackages.com/packages/rawdreeg-phpswitcher)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[illuminate/console

The Illuminate Console package.

13046.0M6.5k](/packages/illuminate-console)[jolicode/castor

A lightweight and modern task runner. Automate everything. In PHP.

54743.1k4](/packages/jolicode-castor)[automattic/jetpack-changelogger

Jetpack Changelogger tool. Allows for managing changelogs by dropping change files into a changelog directory with each PR.

107.2M176](/packages/automattic-jetpack-changelogger)[whatsdiff/whatsdiff

See what's changed in your project's dependencies

771.2k](/packages/whatsdiff-whatsdiff)[dagger/dagger

Dagger PHP SDK

261.1k](/packages/dagger-dagger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)