Named Arguments (PHP 8.0)
debt(d5/e1/b3/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list Rector and phpcs — both specialist/configurable tools rather than default linters. The common mistake of renaming a parameter without treating it as a breaking change (silently breaking named-argument callers) is also not caught by the compiler and requires code review or these specialist tools to detect.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix is literally a one-line replacement at the call site — swap positional arguments for named ones (or vice versa). No structural change needed.
Closest to 'localised tax' (b3). Named arguments impose a burden primarily at the parameter-naming level: renaming a function's parameters becomes a breaking change if callers use named args. This affects only the functions/components that adopt this style, not the entire codebase architecture, though it does create a mild persistent contract around parameter names.
Closest to 'notable trap' (t5). The misconception field states developers treat named arguments as 'just more verbose positional arguments,' missing that they allow skipping optional params and are order-independent. The documented gotcha — that renaming parameters is now a breaking change for callers using named args — is a well-known but frequently overlooked pitfall that most developers encounter eventually.
Also Known As
TL;DR
Explanation
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.
Common Misconception
Why It Matters
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.
Code Examples
// Cryptic positional arguments:
$result = array_slice($users, 1, 5, true); // What does 'true' do here?
// Self-documenting with named arguments:
$result = array_slice($users, offset: 1, length: 5, preserve_keys: true);// Before: cryptic positional arguments
$result = array_slice($array, 2, null, true);
// After: self-documenting with named args
$result = array_slice(array: $array, offset: 2, preserve_keys: true);
// Skip optional parameters you don't need
str_contains(haystack: $html, needle: '</body>');
// Named args in constructors — order doesn't matter
$req = new CreateUserRequest(
email: 'alice@example.com',
role: 'admin',
name: 'Alice',
);