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. rawdreeg/phpswitcher

ActiveProject

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

CLI tool to manage and switch between multiple PHP versions

v0.1.1(1y ago)181MITShellPHP ^8.1CI passing

Since Apr 7Pushed 1mo ago1 watchersCompare

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

READMEChangelog (7)Dependencies (3)Versions (5)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

34

—

LowBetter than 77% of packages

Maintenance73

Regular maintenance activity

Popularity9

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 ~0 days

Total

2

Last Release

397d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5eec3c68f080b056309631ec332d02aac00f2adf5e8a60bf789b4cb0021c8325?d=identicon)[rawdreeg](/maintainers/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)")

###  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

[laravel/framework

The Laravel Framework.

34.6k509.9M17.0k](/packages/laravel-framework)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M647](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[magento/community-edition

Magento 2 (Open Source)

12.1k52.1k10](/packages/magento-community-edition)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)

PHPackages © 2026

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