PVM - PHP Version Manager for Windows

Managing multiple PHP versions on Windows has traditionally been a challenging task for developers. Enter PVM (PHP Version Manager), a command-line tool specifically designed to simplify PHP version management on Windows systems. This comprehensive guide will walk you through everything you need to know about PVM, from installation to advanced usage.

What is PVM ?

PVM is a powerful, command-line PHP version manager built specifically for Windows environments, it addresses the unique challenges Windows developers face when working with multiple PHP versions. What sets PVM apart is its comprehensive approach - it doesn't just manage PHP versions, but also handles extensions, php.ini configurations, and environment variables seamlessly.

Project Structure Overview

PVM follows a well-organized structure that separates concerns and maintains clean code architecture:

pvm/
├── pvm.bat                 # Main executable entry point
├── src/
│   ├── actions/            # Core functionality modules
│   │   ├── setup.ps1       # Installation and setup logic
│   │   ├── install.ps1     # PHP version installation
│   │   ├── use.ps1         # Version switching logic
│   │   ├── ini.ps1         # PHP configuration management
│   │   └── ...             # Other action modules
│   ├── core/               # Core system components
│   │   ├── config.ps1      # Configuration management
│   │   └── router.ps1      # Command routing logic
│   ├── functions/            # Utility functions
│   └── pvm.ps1             # Main PowerShell entry point
└── tests/                  # Test suite directory (Pester tests)
└── storage/                # Data and logging directory
    ├── data/               # Cached data and configurations
    ├── logs/               # Error logs and backups
    └── php/                # PHP installations directory

Key Features

Automated Setup Process: PVM now includes an intelligent setup command that handles PATH variable configuration automatically, eliminating manual environment setup.
Seamless Version Switching: Switch between PHP versions with a single command, making it easy to test applications across different PHP environments.
Extension Management: Built-in support for popular extensions like Xdebug and OPcache, with the ability to enable or disable them per installation.
Direct php.ini Management: Modify PHP settings and manage extensions directly from the command line without manually editing configuration files.
Custom Installation Directories: Install PHP versions in custom locations to suit your specific development setup.
Online Version Discovery: Fetch available PHP versions directly from online sources, ensuring you always have access to the latest releases.
Configuration Backup and Restore: Automatic backup of PATH variables and php.ini settings with easy restoration options.

Prerequisites

- Windows 10/11
- PowerShell 5.1 or later

Installation & Setup

Getting started with PVM has been significantly simplified with the new automated setup process:

Step 1: Clone the Repository

First, clone the PVM repository to your local machine:

git clone https://github.com/drissboumlik/pvm
cd pvm

Step 2: Automated Setup

Run the setup command to automatically configure PVM:

pvm setup

The setup process automatically:

Configures necessary environment variables
Adds PVM to your system PATH
Creates backup of your current PATH configuration
Sets up the PHP version switching mechanism

Command Reference

PVM provides a comprehensive set of commands for managing your PHP installations and configurations:

Getting Help

Display all available commands and their descriptions, serving as your quick reference guide.

pvm help

Display help for a specific command with description, usage and examples

pvm help <command> # Example : pvm help use

Display information about the environment

Display information about the current PHP (version, path, extensions, settings)

pvm info
pvm ini info

Display information about the current PHP extensions

pvm info extensions # pvm ini info extensions

Display information about the current PHP settings

pvm info settings # pvm ini info settings

Display information about the current PHP (version, path, extensions, settings) with specific <term> in their name

pvm info --search=<term> # pvm ini info --search=<term>
# Example : pvm info --search=cache

Checking Current Version

Shows which PHP version is currently active on your system.

pvm current

Listing PHP Versions

Display all PHP versions currently installed on your system.

pvm list # pvm ls

List installed versions with specific version in the name

pvm list --search=<version>
# Example: pvm list --search=8.2

List installed versions matching x86 and nts

pvm list [x86|x64] [ts|nts]
# Example: pvm list x86 nts

View all PHP versions available for installation from your configured sources.

pvm list available # pvm ls available

List installable PHP versions from remote source matching x86 and nts

pvm list available [x86|x64] [ts|nts]
# Example: pvm list available x86 nts

List available versions with specific version in the name

pvm list available --search=<version>
# Example: pvm list available --search=8.2

Installing PHP Versions

Basic Installation:

pvm install <version> # pvm i <version>
# Example: pvm install 8.4 / pvm i 8.4

Install a specific version for a specific arch & build type

pvm install <version> [x86|x64] [ts|nts]
# Example: pvm install 8.4 x64 nts # pvm i 8.4 x64 nts

Install the php version specified on your project.

pvm install auto # pvm i auto

Install the latest available php version.

pvm install latest # pvm i latest

Uninstalling PHP Versions

pvm uninstall <version> # pvm rm <version>
# Example: pvm uninstall 8.4 # pvm rm 8.4

Remove a specific PHP version from your system cleanly, including all associated files and configurations.

Switching Between Versions

pvm use <version> # Example: pvm use 8.4

Switch your active PHP version to the specified version, updating all necessary environment variables automatically.

pvm use auto

When run inside a PHP project, this command checks for a .php-version file and composer.json, then switches to the PHP version specified in either file.

PHP Configuration Management

One of PVM's most powerful features is its ability to manage PHP configurations and extensions directly from the command line:

Extension Management

Check extensions status:

pvm ini status <extension> # Example: pvm ini status xdebug opcache

Enable Extensions:

pvm ini enable xdebug opcache # Example: pvm ini enable xdebug opcache

Disable Extensions:

pvm ini disable xdebug opcache # Example: pvm ini disable xdebug opcache

PHP Settings Management

Set Configuration Values and change the status:

pvm ini set <setting>=<value> [--disable] # Default is enabling the setting
# Example: pvm ini set memory_limit=512M max_file_uploads=20
# Example: pvm ini set max_input_time=60 --disable

Get Configuration Values:

pvm ini get <setting>
# Example: pvm ini get memory_limit max_file_uploads

Install extensions from remote source

pvm ini install <extension>
# Example: pvm ini install opcache

List installed extensions

pvm ini list

List available extensions from remote source

pvm ini list available

List installed extensions with 'zip' in their name

pvm ini list --search=<extension>
# Example: pvm ini list --search=zip

List available extensions with 'zip' in their name

pvm ini list available --search=<extension>
# Example: pvm ini list available --search=zip

Restore Configuration:

pvm ini restore

Restore php.ini settings from backup, useful when you need to revert changes or start fresh.

Check Logs:

pvm log --pageSize=[number] --search=<term> # Default value is 5
# Example: pvm log --pageSize=3 --search=error

This one will help you check the log file in a readable way, with pagination.

Manage PHP Configuration Profiles

Save current PHP configuration to a profile

pvm profile save <name> [description]
# Example: pvm profile save development
# Example: pvm profile save production "Production configuration"

Load and apply a saved profile

pvm profile load <name> # Example: pvm profile load development

List all available profiles

pvm profile list

Show detailed profile contents

pvm profile show <name> # Example: pvm profile show development

Delete a profile

pvm profile delete <name> # Example: pvm profile delete old-profile

Export profile to a JSON file

pvm profile export <name> [path]
# Example: pvm profile export development
# Example: pvm profile export dev ./backup.json

Import profile from a JSON file

pvm profile import <path> [name]
# Example: pvm profile import ./my-profile.json
# Example: pvm profile import ./profile.json custom-name

Profile Structure: Profiles are stored as JSON files in storage/data/profiles/ and contain:

Popular/common PHP settings (key-value pairs with enabled/disabled state)
Popular/common extensions (enabled/disabled state and type)
Metadata (name, description, creation date, PHP version)

Note: Only popular/common settings and extensions are saved in profiles. This keeps profiles focused and manageable.

Running Tests

Run tests against the PowerShell scripts in the repo — especially useful for contributors verifying changes before submitting a pull request:

Requirements

To run tests with, you need to have the Pester testing framework installed. Pester is a testing framework for PowerShell.

Open PowerShell as Administrator and run:

Install-Module -Name Pester -Force -SkipPublisherCheck

💡 If prompted to trust the repository, type Y and press Enter.

You can verify the installation with:

Get-Module -ListAvailable Pester

Run the tests

pvm test [files = (files inside the tests/ directory)] [--exclude=files] [--coverage[=<number>]] [--verbosity=(None|Normal|Detailed|Diagnostic)] [--tag=<tag>] [--sort=[coverage|duration|file]]

# Examples:
pvm test                           # Runs all tests with Normal (default) verbosity.
pvm test use install               # Runs only 'use.tests.ps1' and 'install.tests.ps1' files with Normal verbosity.
pvm test --exclude=use,install     # Runs all tests except use.tests.ps1 and install.tests.ps1 with Normal verbosity.
pvm test --verbosity=Detailed      # Runs all tests with Detailed verbosity.
pvm test --coverage                # Runs all tests and generates coverage report (target: 75%)
pvm test --coverage=80.5           # Runs all tests and generates coverage report (target: 80.5%)
pvm test --sort=duration            # Runs all tests and sort results by duration
pvm test --tag=myTag               # Runs helpers.tests.ps1 and list.tests.ps1 with Diagnostic verbosity and only runs tests with tag "myTag".

Logging and Storage System

PVM maintains essential files for troubleshooting and performance:

Key Files

Error Logging: storage/logs/error.log

Contains detailed error information when commands fail
Check this file first when troubleshooting installation or configuration issues

PATH Backup: storage/logs/path.bak.log

Automatic backup of your system's PATH variable created during setup
Used for system recovery if environment variables need restoration

Available Versions Cache for faster performance:

Cached list of available PHP versions storage/data/available_versions.json
Cached list of available PHP extensions storage/data/available_extensions.json

Final Thoughts

PVM dramatically simplifies PHP version management on Windows, offering a seamless and developer-friendly experience that was long missing from the ecosystem. With its powerful command-line tools, automated setup, and deep integration with extensions and configuration files, PVM empowers developers to focus more on building applications.

What's Next?

Explore the full command list using pvm help
Install your first PHP version with pvm install <version>
Contribute or report issues on GitHub
Share your feedback and suggest features
👉 If you find PVM helpful, consider giving it a star ⭐ on GitHub, an upvote PVM on ProductHunt here or leave a review here) — it really helps others discover the project and keeps development going.