{
    "slug": "php_version_compatibility",
    "term": "Cross-Version Compatibility Testing",
    "category": "php",
    "difficulty": "intermediate",
    "short": "Testing PHP code across multiple versions uses CI matrix builds, phpenv/phpbrew, Docker multi-version setups, and static analysis to catch compatibility issues before deployment.",
    "long": "Strategies: (1) GitHub Actions matrix: [php: ['8.1','8.2','8.3']] runs tests against each version. (2) PHPStan with phpCompatibilityFixer to detect usage of features not available in minimum PHP version. (3) composer check-platform-reqs validates extension requirements. (4) phpenv or phpbrew to switch PHP versions locally. (5) Docker: test against official php:8.x-cli images. (6) PHPCompatibility (PHPCS sniff): checks code against target PHP version. Key: declare minimum PHP version in composer.json require->php field and enforce with tooling.",
    "aliases": [],
    "tags": [
        "php",
        "testing",
        "compatibility",
        "ci",
        "versions"
    ],
    "misconception": "Setting the PHP version requirement in composer.json is sufficient — it documents but doesn't verify compatibility. Use PHPCompatibility sniffs to actually check.",
    "why_it_matters": "Library authors and teams upgrading PHP need to verify compatibility across versions — CI matrix testing catches regressions before they affect users.",
    "common_mistakes": [
        "Only testing against one PHP version in CI.",
        "Not specifying minimum PHP version in composer.json.",
        "Not using PHPCompatibility PHPCS sniffs to catch API usage differences."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php_deprecation_notices",
        "php_migrate_7_to_8",
        "static_analysis",
        "cdn"
    ],
    "prerequisites": [
        "static_analysis",
        "ci_cd"
    ],
    "refs": [
        "https://github.com/PHPCompatibility/PHPCompatibility"
    ],
    "bad_code": "# composer.json — no PHP version constraint:\n{\n    \"require\": {\n        \"php\": \"*\"\n    }\n}",
    "good_code": "# composer.json:\n{\n    \"require\": {\n        \"php\": \">=8.1\"\n    }\n}\n\n# GitHub Actions:\nmatrix:\n  php: ['8.1', '8.2', '8.3']\n\n# phpcs.xml:\n<rule ref=\"PHPCompatibility\"/>\n<config name=\"testVersion\" value=\"8.1-\"/>",
    "quick_fix": "Add PHP version constraint to composer.json. Add PHPCompatibility PHPCS rule. Set up CI matrix for supported PHP versions. Run phpcs --standard=PHPCompatibility.",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_version_compatibility",
        "html_url": "https://codeclaritylab.com/glossary/php_version_compatibility",
        "json_url": "https://codeclaritylab.com/glossary/php_version_compatibility.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Cross-Version Compatibility Testing](https://codeclaritylab.com/glossary/php_version_compatibility) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_version_compatibility"
            }
        }
    }
}