phpvm — PHP Version Manager for Windows

"Git for local PHP runtimes, Nginx web servers & MySQL databases."

phpvm is a lightweight, high-performance runtime version manager and process orchestrator for Windows developers. It gives every PHP project its own isolated environment — exact PHP version, required extension DLLs, FastCGI web server (Nginx), and database (MySQL 8) — without mutating your global system PATH or installing heavy virtual machines.

---

Highlights & Features

• Zero System Mutation: Keeps your global Windows PATH clean. Environment variables are scoped per terminal session or per background process.
• Multi-Version PHP Engine: Seamlessly install and switch between PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4 (NTS x64 builds).
• Auto Extension DLL Resolver: Automatically detects, formats, and appends extension DLLs (php_zip.dll, php_pdo_mysql.dll, php_curl.dll, etc.) on Windows.
• Nginx FastCGI Orchestration: Automatically configures and supervises per-project Nginx web servers and continuous php-cgi.exe FastCGI workers.
• Integrated MySQL 8 Database: Provisions portable, isolated MySQL 8 instances per project with automatic port allocation (3306, 8083, etc.).
• Desktop Control Panel: Includes a built-in dark CLI-vibe web dashboard (http://127.0.0.1:23400) to manage projects, run Laravel Artisan commands, inspect live logs, and view health diagnostics.
• Declarative runtime.yml: Version-control your project's exact PHP, web server, and database requirements so team members get identical local environments.

---

Quick Start (30 Seconds)

1. One-Line Installation (PowerShell)

Run in an administrative or standard PowerShell window:

irm https://raw.githubusercontent.com/Vikrez22/phpvm/main/install.ps1 | iex

2. Initialize a Project

Navigate to your PHP or Laravel project root:

cd C:\projects\my-laravel-app
phpvm init

This creates a runtime.yml manifest and automatically adds .phpvm/ to your .gitignore.

3. Install & Start Runtimes

phpvm install
phpvm up

Your web application is now live at http://localhost:8000 (or http://localhost:8001) with MySQL 8 running on 127.0.0.1:8083!

4. Launch Desktop Control Panel

phpvm gui

Open http://127.0.0.1:23400 to manage active services, view live log streams, and copy Artisan CLI commands.

---

Command Reference

Service Supervision & Environment

Command	Description
phpvm init	Generate a runtime.yml manifest in the current directory
phpvm install [pack]	Install a runtime pack (php@8.3, nginx@1.30, mysql@8) or manifest dependencies
phpvm up [--no-server] [--no-db]	Start Nginx, PHP-CGI, and MySQL processes for the project
phpvm down [--all]	Gracefully stop running project services
phpvm status	Display allocated ports, process PIDs, web URLs, and database connections
phpvm logs [service]	View live log streams (web, mysql, nginx, php-cgi)
phpvm run <cmd>	Execute a command (e.g. php artisan migrate) using project PHP
phpvm shell	Launch an interactive PowerShell session scoped to project PHP & Composer
phpvm doctor	Run diagnostic checks for VC++ redistributables, permissions, and PATH
phpvm gui	Launch the Desktop Control Panel web dashboard (http://127.0.0.1:23400)

Version & Pack Management

Command	Description
phpvm use <version>	Temporarily activate a specific PHP version in current shell
phpvm list [--available]	List installed (or upstream available) PHP versions and service packs
phpvm uninstall <pack>	Remove an installed runtime or service pack
phpvm snapshot <name>	Backup project runtime state and data to a .tar.gz archive
phpvm restore <name>	Restore project runtime state from a backup archive
phpvm update	Update phpvm binary and pull latest upstream registry index

---

Declarative Manifest (runtime.yml)

Every project declares its dependencies in runtime.yml:

# runtime.yml - managed by phpvm
phpvm: "1"

runtime:
  php: "8.3"
  composer: "latest"

extensions:
  - zip
  - pdo_mysql
  - curl
  - mbstring
  - openssl
  - fileinfo
  - gd

database:
  engine: mysql
  version: "8.4"
  port: 8083

server:
  engine: nginx
  port: 8000
  root: public

project:
  name: my-laravel-app
  domain: my-laravel-app.local

---

Architecture & Storage

• Global Runtime Cache: Installed PHP builds, Nginx binaries, and MySQL distributions are stored immutably in %APPDATA%\phpvm\runtimes\ and %APPDATA%\phpvm\services\.
• Project State Isolation: Per-project generated php.ini, Nginx configuration, process PIDs, and MySQL data folders are kept inside .phpvm/ in your project directory.
• Git Friendly: .phpvm/ is automatically ignored in .gitignore, keeping your Git working tree clean.

---

Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

Distributed under the MIT License. See LICENSE for more information.