Named Arguments in Built-in PHP Functions
debt(d5/e3/b5/t5)
Closest to 'specialist tool catches' (d5). PHPStan and Psalm from detection_hints.tools can detect parameter name mismatches and flag when named arguments reference non-existent parameters, but this requires static analysis tooling rather than default linting.
Closest to 'simple parameterised fix' (e3). Per quick_fix, the fix involves updating parameter names or removing named argument usage — typically a search-and-replace pattern within affected call sites. May touch multiple files but follows a consistent pattern.
Closest to 'persistent productivity tax' (b5). The term applies across web/cli/queue-worker contexts per applies_to. Once named arguments are adopted in a codebase, parameter names become part of the public API contract, requiring ongoing attention during refactoring and version upgrades — a persistent but not system-defining consideration.
Closest to 'notable trap' (t5). The misconception states developers assume 'named arguments work identically for all PHP built-in functions' when parameter names may differ between extensions and versions. This is a documented gotcha that developers eventually learn, but the inconsistency with variadic functions and cross-version parameter naming creates real surprise.
Also Known As
TL;DR
Explanation
Named arguments (PHP 8.0) apply to built-in functions as well as userland code. This is particularly valuable for functions with many positional parameters where intermediate defaults must be skipped: array_slice($array, offset: 2, preserve_keys: true) is far clearer than array_slice($array, 2, null, true). Common built-in targets: str_contains, implode, array_map, array_filter (with mode:), htmlspecialchars (flags:, encoding:), json_encode (flags:, depth:). Caution: built-in parameter names are part of PHP's public API from 8.0 onward but some names changed between versions — check the manual. Named arguments cannot be used with variadic functions that spread into ...$args.
Common Misconception
Why It Matters
Common Mistakes
- Not using named arguments for built-in functions with confusing parameter order — str_contains vs strpos argument order differs.
- Renaming function parameters in your own API and forgetting it is a breaking change for named argument callers.
- Using named arguments with variadic functions — they interact in non-obvious ways.
- Not using named arguments for clarity in calls with boolean flags: htmlspecialchars($str, double_encode: false).
Code Examples
// Confusing positional arguments:
$result = array_slice($arr, 1, 5, true); // What is 'true'?
$encoded = htmlspecialchars($str, ENT_QUOTES | ENT_HTML5, 'UTF-8', false); // Last arg?
// Named — self-documenting:
$result = array_slice($arr, offset: 1, length: 5, preserve_keys: true);
$encoded = htmlspecialchars($str, double_encode: false);// Skip intermediate positional arguments cleanly
$slice = array_slice($items, offset: 5, preserve_keys: true);
$encoded = json_encode($data, flags: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);