oraios/serena · error · RuntimeError

PHP {major}.{minor} detected, but Phpactor requires PHP 8.1+

Error message

PHP {major}.{minor} detected, but Phpactor requires PHP 8.1+. Please upgrade PHP.

What it means

Raised by Phpactor's _get_or_install_core_dependency when the detected PHP runtime version (parsed from `php -v` output via /PHP (\d+)\.(\d+)/) is below 8.1. Phpactor requires PHP 8.1 or newer, so the library refuses to proceed rather than fail later with cryptic errors.

Source

Thrown at src/solidlsp/language_servers/phpactor.py:78

            Setup runtime dependencies for Phpactor and return the path to the PHAR file.
            """
            phpactor_version = self._custom_settings.get("phpactor_version", DEFAULT_PHPACTOR_VERSION)
            phpactor_phar_url = f"https://github.com/phpactor/phpactor/releases/download/{phpactor_version}/phpactor.phar"
            # Verify PHP is installed
            php_path = shutil.which("php")
            assert php_path is not None, (
                "PHP is not installed or not found in PATH. Phpactor requires PHP 8.1+. Please install PHP and try again."
            )

            # Check PHP version (Phpactor requires PHP 8.1+)
            result = subprocess_run(["php", "--version"], capture_output=True, text=True, check=False)
            php_version_output = result.stdout.strip()
            log.info(f"PHP version: {php_version_output}")
            version_match = re.search(r"PHP (\d+)\.(\d+)", php_version_output)
            if version_match:
                major, minor = int(version_match.group(1)), int(version_match.group(2))
                if major < 8 or (major == 8 and minor < 1):
                    raise RuntimeError(f"PHP {major}.{minor} detected, but Phpactor requires PHP 8.1+. Please upgrade PHP.")
            else:
                log.warning("Could not parse PHP version from output. Continuing anyway.")

            # legacy unversioned phar at root reserved for INITIAL; every other version goes into a versioned subdir
            if phpactor_version == INITIAL_PHPACTOR_VERSION:
                phar_dir = self._ls_resources_dir
            else:
                phar_dir = os.path.join(self._ls_resources_dir, f"phpactor-{phpactor_version}")
            phpactor_phar_path = os.path.join(phar_dir, "phpactor.phar")
            if not os.path.exists(phpactor_phar_path):
                os.makedirs(phar_dir, exist_ok=True)
                log.info(f"Downloading phpactor PHAR from {phpactor_phar_url}")
                FileUtils.download_and_extract_archive_verified(
                    phpactor_phar_url,
                    phpactor_phar_path,
                    "binary",
                    expected_sha256=_phpactor_sha(phpactor_version),
                    allowed_hosts=PHPACTOR_ALLOWED_HOSTS,

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Upgrade PHP to >= 8.1 (e.g. on Debian/Ubuntu use the sury/ondrej PPA: `sudo apt install php8.2-cli`).
2. If multiple PHP versions exist, ensure a >= 8.1 binary comes first on PATH (adjust PATH or use update-alternatives / brew link php@8.2).
3. In CI, bump the setup-php action / Docker image to PHP 8.1+.
4. Verify with `php -v` in the same environment that launches the server before retrying.

Example fix

// before (shell, Ubuntu 20.04)
php -v  # PHP 7.4.33
python -m app  # RuntimeError
// after
sudo add-apt-repository ppa:ondrej/php
sudo apt update && sudo apt install php8.2-cli
sudo update-alternatives --set php /usr/bin/php8.2
php -v  # PHP 8.2.x
python -m app

import re, subprocess
def php_meets_requirement(min_major=8, min_minor=1):
    out = subprocess.run(["php", "-v"], capture_output=True, text=True).stdout
    m = re.search(r"PHP (\d+)\.(\d+)", out)
    if not m:
        return False
    major, minor = int(m.group(1)), int(m.group(2))
    return (major, minor) >= (min_major, min_minor)

When it happens

Trigger: Instantiating the Phpactor-based PHP language server when the php binary on PATH reports e.g. PHP 7.4 or 8.0; the parsed major.minor < 8.1 triggers the error. If the version string can't be parsed at all, it only logs a warning and continues.

Common situations: Old system PHP on Ubuntu 20.04/Debian (7.4); multiple PHP versions installed with an older one first on PATH; macOS stock PHP or old Homebrew PHP; CI images pinned to PHP 7.x; XAMPP/MAMP shipping PHP < 8.1.

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/56196879ddbf213b. Report an issue: GitHub.