refactor: enhance PHP installation process with intelligent repository detection and setup guidance for RHEL/Fedora systems

Author: Thavarshan

CHANGELOG.md

@@ -2,12 +2,19 @@
 
 ## [v1.6.0] - 2025-09-15
 
+### Added
+
+- **Smart repository detection:** Added intelligent detection of missing PHP repositories on RHEL/Fedora systems with automatic suggestions for enabling Remi's repository.
+- **Enhanced error messaging:** Implemented comprehensive error handling with actionable solutions when PHP packages are not found in default repositories.
+- **Repository setup guidance:** Added detailed step-by-step instructions for enabling EPEL and Remi repositories on Fedora, RHEL, Rocky Linux, AlmaLinux, and CentOS systems.
+
 ### Changed
 
 - **Consolidated GitHub Actions workflows:** Streamlined CI/CD from 7 separate workflow files down to 3 focused workflows, eliminating duplication while maintaining comprehensive test coverage.
 - **Enhanced multi-distribution testing:** Expanded automated testing to cover 13 Linux distributions (Ubuntu, Debian, Fedora, Rocky Linux, AlmaLinux, Arch Linux, Alpine Linux) with 4 different package managers (apt, dnf, pacman, apk).
 - **Improved cross-platform compatibility:** Fixed package installation issues for RHEL-family distributions (Rocky/Alma Linux) and Alpine Linux in CI environments.
 - **Streamlined workflow organization:** Reorganized tests into logical categories: syntax analysis, core functionality, PHP usage, multi-distribution compatibility, performance testing, and end-to-end integration.
+- **Intelligent PHP installation:** Enhanced PHP installation process to check package availability before attempting installation and provide specific guidance when packages are missing.
 
 ### Fixed
 

README.MD

@@ -41,11 +41,13 @@ PHP 8.1.13
 - Seamlessly switch between installed PHP versions.
 - Auto-switch PHP versions based on project `.phpvmrc`.
 - 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.
+- **Intelligent package availability checking** before attempting installations.
 - Enhanced cross-platform compatibility with improved shell support.
 - Works with common shells (`bash`, `zsh`).
 - Comprehensive version commands (`phpvm version`, `phpvm --version`, `phpvm -v`).
 - Post-install validation with helpful warnings for missing binaries.
-- Improved error handling with detailed messages and suggestions.
 - Enhanced Homebrew integration with better link failure detection.
 - Informative, color-coded feedback with timestamps for logs.
 - Includes unit tests with BATS for automated testing.
@@ -108,6 +110,8 @@ To install a specific version of PHP:
 phpvm install 8.1
 ```
 
+**Smart Repository Detection**: On RHEL/Fedora systems, phpvm automatically detects if PHP packages are available in your current repositories. If not, it provides step-by-step instructions to enable the necessary repositories (like Remi's repository) before installation.
+
 ### Switching PHP Versions
 
 To switch between installed versions:
@@ -196,6 +200,8 @@ export PATH="$PHPVM_DIR/bin:$PATH"
 
 If you experience issues with `phpvm`, try the following:
 
+### General Issues
+
 - Run `phpvm test` to verify all functions are working correctly
 - Check the phpvm version with `phpvm version` or `phpvm --version`
 - Ensure your shell profile is sourcing `phpvm.sh`
@@ -209,6 +215,53 @@ If you experience issues with `phpvm`, try the following:
 - If you encounter Homebrew link issues on macOS, try manually relinking: `brew unlink [email protected] && brew link --force [email protected]`
 - Refer to the [Changelog](./CHANGELOG.md) for recent updates and fixes
 
+### Repository Setup for RHEL/Fedora Systems
+
+If you encounter "PHP packages not found" errors on RHEL-family distributions, phpvm will automatically provide setup instructions. You can also manually enable the required repositories:
+
+#### Fedora Systems
+
+```bash
+# Install Remi's repository
+sudo dnf install https://rpms.remirepo.net/fedora/remi-release-$(rpm -E %fedora).rpm
+
+# Enable the repository
+sudo dnf config-manager --set-enabled remi
+
+# Enable specific PHP version (example for PHP 8.3)
+sudo dnf config-manager --set-enabled remi-php83
+```
+
+#### RHEL/Rocky/AlmaLinux/CentOS Systems
+
+```bash
+# Install EPEL repository
+sudo dnf install epel-release
+
+# Install Remi's repository
+sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-$(rpm -E %rhel).rpm
+
+# Enable the repositories
+sudo dnf config-manager --set-enabled remi
+sudo dnf config-manager --set-enabled remi-php83  # for PHP 8.3
+```
+
+#### Alternative: Use Homebrew on Linux
+
+If you prefer to avoid repository management, you can install Homebrew on Linux:
+
+```bash
+# Install Homebrew on Linux
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Add to your shell profile
+echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
+source ~/.bashrc
+
+# Now phpvm will use Homebrew instead of dnf/yum
+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.sh

@@ -2,9 +2,9 @@
 
 # phpvm - A PHP Version Manager for macOS and Linux
 # Author: Jerome Thayananthajothy ([email protected])
-# Version: 1.5.0
+# Version: 1.6.0
 
-PHPVM_VERSION="1.5.0"
+PHPVM_VERSION="1.6.0"
 
 # Define a debug mode for testing
 if [ "${BATS_TEST_FILENAME:-}" != "" ]; then
@@ -264,6 +264,109 @@ validate_php_version() {
     return 1
 }
 
+# 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
+    else
+        return 1
+    fi
+}
+
+# Detect if PHP packages are available in current repositories
+detect_php_availability() {
+    version="$1"
+
+    case "$PKG_MANAGER" in
+    dnf)
+        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
+            # Some PHP packages exist, but not the requested version
+            return 2
+        else
+            # No PHP packages found at all
+            return 1
+        fi
+        ;;
+    yum)
+        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
+            return 2
+        else
+            return 1
+        fi
+        ;;
+    apt)
+        if apt-cache search "php$version" 2>/dev/null | grep -q "php$version"; then
+            return 0
+        else
+            return 1
+        fi
+        ;;
+    *)
+        # For other package managers, assume available
+        return 0
+        ;;
+    esac
+}
+
+# Provide repository setup suggestions for RHEL/Fedora systems
+suggest_repository_setup() {
+    version="$1"
+
+    if [ "$PKG_MANAGER" = "dnf" ] || [ "$PKG_MANAGER" = "yum" ]; then
+        if [ "$LINUX_DISTRO" = "fedora" ]; then
+            phpvm_echo ""
+            phpvm_echo "PHP packages not found in default Fedora repositories."
+            phpvm_echo "To install PHP $version, you need to enable Remi's repository:"
+            phpvm_echo ""
+            phpvm_echo "  # Install Remi's repository"
+            if [ -n "$LINUX_VERSION" ]; then
+                phpvm_echo "  sudo dnf install https://rpms.remirepo.net/fedora/remi-release-$LINUX_VERSION.rpm"
+            else
+                phpvm_echo "  sudo dnf install https://rpms.remirepo.net/fedora/remi-release-42.rpm"
+            fi
+            phpvm_echo ""
+            phpvm_echo "  # Enable the repository"
+            phpvm_echo "  sudo dnf config-manager --set-enabled remi"
+            phpvm_echo ""
+            phpvm_echo "  # Enable specific PHP version repository"
+            major_minor=$(echo "$version" | cut -d. -f1,2 | tr -d '.')
+            phpvm_echo "  sudo dnf config-manager --set-enabled remi-php$major_minor"
+            phpvm_echo ""
+            phpvm_echo "After setting up the repository, try: phpvm install $version"
+
+        elif [ "$LINUX_DISTRO" = "rhel" ] || [ "$LINUX_DISTRO" = "rocky" ] || [ "$LINUX_DISTRO" = "almalinux" ] || [ "$LINUX_DISTRO" = "centos" ]; then
+            phpvm_echo ""
+            phpvm_echo "PHP packages not found in default RHEL/CentOS repositories."
+            phpvm_echo "To install PHP $version, you need to enable EPEL and Remi repositories:"
+            phpvm_echo ""
+            phpvm_echo "  # Install EPEL repository"
+            phpvm_echo "  sudo dnf install epel-release"
+            phpvm_echo ""
+            phpvm_echo "  # Install Remi's repository"
+            if [ -n "$LINUX_VERSION" ]; then
+                major_version=$(echo "$LINUX_VERSION" | cut -d. -f1)
+                phpvm_echo "  sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-$major_version.rpm"
+            else
+                phpvm_echo "  sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-9.rpm"
+            fi
+            phpvm_echo ""
+            phpvm_echo "  # Enable the repositories"
+            phpvm_echo "  sudo dnf config-manager --set-enabled remi"
+            major_minor=$(echo "$version" | cut -d. -f1,2 | tr -d '.')
+            phpvm_echo "  sudo dnf config-manager --set-enabled remi-php$major_minor"
+            phpvm_echo ""
+            phpvm_echo "After setting up the repositories, try: phpvm install $version"
+        fi
+    fi
+}
+
 # Install PHP using the detected package manager
 install_php() {
     version="$1"
@@ -357,18 +460,51 @@ install_php() {
         ;;
     dnf)
         # Fedora/RHEL 8+ with dnf
+        # First, check if PHP packages are available
+        detect_php_availability "$version"
+        availability_status=$?
+
+        if [ $availability_status -eq 1 ]; then
+            # No PHP packages found - suggest repository setup
+            phpvm_err "PHP packages not found in current repositories."
+            suggest_repository_setup "$version"
+            return 1
+        elif [ $availability_status -eq 2 ]; then
+            # 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
+            phpvm_echo ""
+            if ! check_remi_repository; then
+                phpvm_echo "For more PHP versions, consider enabling Remi's repository:"
+                suggest_repository_setup "$version"
+            fi
+            return 1
+        fi
+
+        # Packages are available, proceed with installation
         if [ "$LINUX_DISTRO" = "fedora" ]; then
             # Fedora uses different PHP packages
             if ! run_with_sudo dnf install -y php"$version" php"$version"-cli; then
-                phpvm_err "Failed to install PHP $version. Package php$version may not exist."
-                phpvm_warn "Check available versions with: dnf search php"
+                phpvm_err "Failed to install PHP $version."
+                # Check if Remi repository might help
+                if ! check_remi_repository; then
+                    phpvm_echo ""
+                    phpvm_echo "If the package wasn't found, you might need Remi's repository:"
+                    suggest_repository_setup "$version"
+                fi
                 return 1
             fi
         else
             # RHEL/CentOS with dnf
             if ! run_with_sudo dnf install -y php"$version"; then
-                phpvm_err "Failed to install PHP $version. Package php$version may not exist."
-                phpvm_warn "You may need to enable EPEL or Remi repository"
+                phpvm_err "Failed to install PHP $version."
+                # Check if repositories might help
+                if ! check_remi_repository; then
+                    phpvm_echo ""
+                    phpvm_echo "You may need to enable additional repositories:"
+                    suggest_repository_setup "$version"
+                fi
                 return 1
             fi
         fi
@@ -382,10 +518,32 @@ install_php() {
             fi
         fi
 
+        # Check PHP availability first
+        detect_php_availability "$version"
+        availability_status=$?
+
+        if [ $availability_status -eq 1 ]; then
+            # No PHP packages found - suggest repository setup
+            phpvm_err "PHP packages not found in current repositories."
+            suggest_repository_setup "$version"
+            return 1
+        elif [ $availability_status -eq 2 ]; then
+            # Some PHP packages exist, but not the requested version
+            phpvm_warn "PHP $version not found, but other PHP versions are available."
+            if ! check_remi_repository; then
+                phpvm_echo "For more PHP versions, consider enabling Remi's repository:"
+                suggest_repository_setup "$version"
+            fi
+            return 1
+        fi
+
         if ! run_with_sudo yum install -y php"$version"; then
-            phpvm_err "Failed to install PHP $version. Package php$version may not exist."
-            phpvm_warn "Consider enabling EPEL: sudo yum install epel-release"
-            phpvm_warn "Consider enabling Remi: sudo yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm"
+            phpvm_err "Failed to install PHP $version."
+            if ! check_remi_repository; then
+                phpvm_echo ""
+                phpvm_echo "You may need to enable additional repositories:"
+                suggest_repository_setup "$version"
+            fi
             return 1
         fi
         ;;