spv

Swap PHP Version (SPV) v3

by Dwayne Pivac @ OMI Ltd.

SPV is a high-density, lightweight, zero-dependency, Perl based CLI utility for developers to manage multiple PHP environments on Windows by modifying the Registry directly. No complex environments, no symlink magic - just clean %PATH% management.
Built entirely in Perl as a standalone app.

Features

• Zero-config switching : Automatically handles PATH injection for User or System hives.
• Smart Archives : Scrapes windows.php.net (configurable) to find and download any version matching your architecture.
• Safety First : Detects if a version is already active to prevent redundant registry writes.
• Fuzzy Command Logic : Supports shortened commands (e.g., cfg for configuration) and common typos (e.g., versoin) so you don't have to be perfect to be fast. See Commands and Aliases for the full list.
• Configurable via CLI : You can change the configuration directly via SPV. No need to manually edit text files.
  
• Pretty print %PATH% : With path you can view your PATH environment with each path on a new line.
  
• Favourite Version : Quickly switch to your favourite (most commonly used) PHP version with spv fave.
  

Prerequisites - Before You Start

• Perl 5.10+: Ensure Perl is in your PATH. Standard distributions like Strawberry Perl are recommended.
• PHP Directories: You must have at least one PHP version downloaded or installed (e.g., via WAMP, XAMPP, or manual zip extracts).
• Initial Setup Logic: If PHP is not already in your Windows PATH, SPV cannot "auto-detect" it. During the first perl spv.pl config run, you must provide the full physical path to your PHP root directory (e.g., c:\wamp64\bin\php or c:\php_installs).
• Archive::Zip Perl Module: This is required for the install command to unpack new PHP versions. Install it via: cpan Archive::Zip or cpanm Archive::Zip
• OS Compatibility: Windows 7, 8, 10, and 11.
• Elevated CLI Access: While SPV can manage User paths (HKCU), Administrator/Elevated access is required to modify System paths (HKLM).

Installation

1. Get the Repo

Clone method

Open a Command Prompt (Admin) and change to the directory you wish to install SPV.
Then clone the repo :

cd /usr/bin/spv
git clone https://vcs.nz/ominz/spv.git .

The app will download directly into the directory you are in.
The trailing dot in the clone command above means current directory.

Direct download method

• Download .zip direct
  
  • or -
    
• Download .gz direct
  
  

Then unzip the files into the directory you will run SPV from.

2. Configuration

Run the configuration command perl spv.pl config. The utility will walk you through several key preferences to tailor the environment to your machine:

• PHP Root Directory: The parent directory containing your various PHP version directories (e.g., c:\wamp64\bin\php).
  SPV will attempt to auto-detect this via your %PATH%. (See the PATH note below).
• Favourite Version: Set a specific version for the spv fave command.
  This can be left blank for now, but if you have a primary version you switch to most often, enter it here.
• Architecture: Define your OS architecture (32 for x86 or 64 for x64).
  SPV will try to determine this automatically from your system environment to ensure the install command fetches the correct binaries.
• Thread Safety: Specify ts (Thread Safe) or nts (Non-Thread Safe).
  SPV will attempt to detect your preference based on any existing PHP installation it finds.
• Install Columns: Adjust the visual layout of the version list displayed during the install process.
  (Default: 6).
• Download URL: The remote repository used to scrape and download new PHP versions.
  (Default URL: https://windows.php.net/downloads/releases/archives/).
• PATH Sort View: Defines how your directories are displayed when running spv path. Use registry to maintain the actual Windows inheritance order (System then User), or alpha for a de-duplicated, alphabetical list in lowercase.
  (Default: registry).
  

Thread Safety note :
NTS - Use this if you run PHP through IIS (FastCGI) or Nginx.
TS - Use this if you run PHP as an Apache Module.

PHP PATH note :
If PHP is not in your path ...
When prompted for the PHP Root, paste the path to your PHP binaries directory.
After you've run the configuration, run perl spv.pl list to get a list of available PHP versions you can switch to.
Then run perl spv.pl use [version] to officially link your chosen PHP version to your Windows PATH.

3. Optional - Run Setup

Setup generates a wrapper spv.cmd and offers to add the directory to your Windows PATH automatically.

perl spv.pl setup

Note :
If you say 'no', you'll need to manually move the generated spv.cmd to a directory already in your PATH.
You can use SPV to list all known PATHs : perl spv.pl path

4. Verify

Close and reopen your console (or run refresh if you use Cmder) to refresh the environment.

spv list

Usage

List Versions

Shows all available PHP versions found in your configured PHP root.
The active version is marked with a *.

spv list

Switch Version

Updates your Windows Registry PATH to use the specified version.
SPV is smart: it finds where your current PHP sits and swaps it in-place, maintaining your PATH order.

spv use 8.1.20

or simply leave out use. SPV knows what you mean ;)

spv 8.1.20

Switch to Favourite

Quickly switch to your pre-defined favourite PHP version (configured via config).

spv favourite

or even shorter is

spv fave

Install New PHP Versions

Scrapes the configured download URL to find available versions.
You choose a version from the interactive list provided.

spv install

Note :
This requires the Archive::Zip Perl module.

View the PATH environment

Displays a list of your current Windows PATH directories, with one entry per line.

spv path

SPV and active PHP Version

Displays SPV version information and the version for the php.exe currently active in your PATH.

spv version

Locate PHP Instances

Scans your current PATH to find every instance of php.exe. Useful for finding conflicting installations.

spv where

Update Configuration

Re-run the configuration utility to update your PHP root, architecture, or other preferences.

spv configuration

or type less with

spv config

About SPV

Displays detailed information about the app logic, versioning, and the developer.

spv about

Help and Options

Displays a full summary of all available commands, including usage examples.

spv help

Technical Notes for Developers

• Registry Driven: We don't use SETX (which truncates at 1024 chars). We write directly to HKLM (if Admin) or HKCU to ensure safety and support for long PATH strings.
• Path Integrity: The use command performs an "in-place swap."
  It identifies the existing PHP entry and replaces it at the same index, ensuring your tool priority remains intact.
• Strict Windows Formatting: All paths are standardized to lowercase drive letters and backslashes (\) for maximum compatibility with the Windows Command Processor.
• De-duplication: Every time you use or setup, the tool automatically vacuums your PATH, removing empty entries and duplicates.
• Config File: If you prefer to edit direct, you can use # for comments on a new line or after you config setting.
  Use quotes ( ` ' ") if you value contains a colon ( : ).
  All your good work will be lost if you run the interactive configuration (spv config)

Commands and Aliases

All commands have aliases. Shortcut ways of getting the job done quicker.
It's also helpful if, lkie me, you can't sepll.
Note all configs are case insensitive.

Full Command	Aliases
list	l ls lsit -l --l -list --list
use	u ues switch -u --u -use --use
version	v ver vers versoin -v --v -version --version
path	p pth paht -p --p -path --path
where	w whereis wheres where's whers locate find -w --w -where --where
install	i in inst instal intsal -i --i -install --install
about	a abuot abowt abut abot inf info information infomation -a --a -about --about
help	h ? hlp help! ! -? -h --h -help --help
configuration	c config conf cfg cf -c --c -config --config
favourite	f fave fav favorite -f --f -fave --fave
setup	s set-up stup cmd makecmd make-cmd bat batch makebat make-bat -s --s -setup --setup

Troubleshooting

SSL Certificate Error during Clone

If you see the following error when trying to clone the repository:

fatal: unable to access '...': SSL certificate problem: unable to get local issuer certificate

This usually means Git cannot find its Certificate Authority bundle.
You can fix this by pointing Git to the correct .crt file (adjust the path to match your actual Cmder/Git location):

git config --global http.sslcainfo "c:\usr\cmder\vendor\git-for-windows\mingw64\ssl\certs\ca-bundle.crt"

Git Config "No such file or directory"

If running the git config command above results in:

error: could not lock config file ...: No such file or directory

Your %HOME% environment variable is pointing to a directory that does not exist.
Ensure your %HOME% variable is set to a valid path (like your %USERPROFILE%) before running the command.

Silent "Fatal" Error

If a git clone fails with a fatal: message but no following text, check your hosts file.
If you are on a local network where the router intercepts HTTPS traffic,
(e.g., redirecting to a setup page), you must manually map the domain to the correct internal IP in:
c:\Windows\System32\drivers\etc\hosts

Advanced CLI Integration

By default, Windows requires you to type perl spv.pl. To run SPV as a first-class command (e.g., just typing spv list), you need to configure two things: PATHEXT and File Association.

1. Enable Extensionless Execution (PATHEXT)

Windows uses the PATHEXT variable to determine which file types it can run without typing the extension. Adding .PL allows you to type spv instead of spv.pl.

Check your current list:

echo %PATHEXT%

Add .PL (User Level) if it's not in your PATHEXT:

setx PATHEXT "%PATHEXT%;.PL"

2. Fix Argument Passing (%*)

Even if .pl files are associated with Perl, Windows often fails to pass arguments (like version numbers) to the script. To fix this, the registry association must be updated to include %*.

The Logic:

• Clear Overrides: Windows "UserChoice" registry keys often block manual associations. These must be cleared.
• Update Command: The open command for Perl scripts should look like this: "C:\path\to\perl.exe" "%1" %*
• The magic ingredient: %* - it ensures that when you type spv use 8.4.1, the 8.4.1 actually reaches the script.

Glossary

cid-6559

SPV : Swap PHP Version

cid-3612

CLI : Command line interface

cid-4131

PHP : PHP Hypertext Preprocessor

cid-4589

WAMP : Windows Apache MySQL PHP

cid-6562

XAMPP : Cross-Platform, Apache, MySQL, PHP and Perl

cid-6564

HKCU : HKEY_CURRENT_USER

cid-6565

HKLM : HKEY_LOCAL_MACHINE

cid-5122

OS : Operating System

cid-2211

URL : Universal Resource Locator

cid-6560

NTS : Non-Thread Safe

cid-6561

TS : Thread Safe

cid-2896

IIS : Microsoft Internet Information Services