{
    "slug": "named_arguments",
    "term": "Named Arguments (PHP 8.0)",
    "category": "php",
    "difficulty": "beginner",
    "short": "Pass arguments to a function by parameter name rather than position, improving readability and allowing optional parameters to be skipped.",
    "long": "Named arguments (PHP 8.0+) allow calling functions with label: $value syntax, making long argument lists self-documenting and enabling skipping of optional parameters without passing null placeholders. For example, array_slice($array, offset: 2, preserve_keys: true) is clearer than array_slice($array, 2, null, true). They also work with built-in functions and constructors. Named arguments are positional-order-independent, but must come after positional arguments.",
    "aliases": [
        "PHP named arguments",
        "named parameters",
        "PHP 8 named args"
    ],
    "tags": [
        "php8",
        "php",
        "syntax"
    ],
    "misconception": "Named arguments are just more verbose positional arguments. Named arguments allow skipping optional parameters, improve readability of calls with many arguments, and are order-independent — they also make code more resilient to function signature changes that add parameters in the middle.",
    "why_it_matters": "Named arguments (PHP 8.0+) let you pass arguments by parameter name in any order — they make calls with many optional parameters self-documenting and eliminate error-prone positional argument counting.",
    "common_mistakes": [
        "Using named arguments for all calls — they are most valuable when skipping optional parameters or for clarity.",
        "Renaming function parameters without treating it as a breaking change — named argument callers break silently.",
        "Not using named arguments with built-in functions that have confusing parameter order — e.g., array_slice($arr, offset: 2, length: 5).",
        "Mixing positional and named arguments where the positional arguments come after named ones — PHP requires positional arguments first."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "long_parameter_list",
        "constructor_promotion"
    ],
    "prerequisites": [
        "constructor_promotion",
        "type_declarations",
        "php_str_functions_80"
    ],
    "refs": [
        "https://www.php.net/manual/en/functions.arguments.php#functions.named-arguments"
    ],
    "bad_code": "// Cryptic positional arguments:\n$result = array_slice($users, 1, 5, true); // What does 'true' do here?\n\n// Self-documenting with named arguments:\n$result = array_slice($users, offset: 1, length: 5, preserve_keys: true);",
    "good_code": "// Before: cryptic positional arguments\n$result = array_slice($array, 2, null, true);\n\n// After: self-documenting with named args\n$result = array_slice(array: $array, offset: 2, preserve_keys: true);\n\n// Skip optional parameters you don't need\nstr_contains(haystack: $html, needle: '</body>');\n\n// Named args in constructors — order doesn't matter\n$req = new CreateUserRequest(\n    email: 'alice@example.com',\n    role:  'admin',\n    name:  'Alice',\n);",
    "quick_fix": "Use named arguments for functions with many parameters to make call sites self-documenting: array_slice(array: $arr, offset: 2, length: 5)",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/named_arguments",
        "html_url": "https://codeclaritylab.com/glossary/named_arguments",
        "json_url": "https://codeclaritylab.com/glossary/named_arguments.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": "[Named Arguments (PHP 8.0)](https://codeclaritylab.com/glossary/named_arguments) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/named_arguments"
            }
        }
    }
}