Named Arguments with Spread Operator
debt(d5/e3/b3/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list Rector and PHPStan as tools — both are specialist static analysis tools rather than default linters. PHPStan can flag incorrect spread usage (wrong key types, version incompatibility) and Rector can identify old call_user_func_array patterns that could be modernised. These tools require deliberate integration and configuration, placing this squarely at d5.
Closest to 'simple parameterised fix' (e3). The quick_fix is straightforward — replace call_user_func_array() or manually built argument arrays with fn(...$namedArgs) — but it requires verifying that array keys match parameter names and checking the PHP version floor is 8.1+. This is a small, targeted refactor within one component rather than a single-line swap, placing it at e3.
Closest to 'localised tax' (b3). The applies_to scope covers web, cli, and queue-worker contexts broadly, but the actual burden is localised to call sites using dynamic dispatch patterns. Most of the codebase is unaffected; only functions that receive or forward argument arrays pay the tax of ensuring string keys match parameter names. This is a recurring but contained concern, placing it at b3.
Closest to 'notable trap' (t5). The misconception field explicitly states that developers believe named arguments and spread cannot be combined at all — a documented PHP 8.1 gotcha. The common_mistakes reinforce this: numerically indexed arrays silently fail or error, pre-8.1 code breaks, and mixing positional spread with named arguments creates ambiguity. These are well-documented but non-obvious surprises that most developers learn only after encountering them, placing this at t5.
Also Known As
TL;DR
Explanation
PHP 8.1 extended the spread operator to support string-keyed arrays, enabling named argument unpacking: function create(string $name, int $age): User {} can be called with $args = ['name' => 'Alice', 'age' => 30]; create(...$args). This is particularly useful for forwarding configuration arrays to functions, building flexible factory methods, and passing captured named arguments between layers. The spread array must use string keys matching parameter names exactly — positional and named spreads cannot be mixed. Combined with named arguments (PHP 8.0), this enables highly readable and order-independent API surfaces.
Common Misconception
Why It Matters
Common Mistakes
- Spreading a numerically indexed array into a function expecting named arguments — keys must match parameter names.
- Using spread with named arguments before PHP 8.1 where string key spread was not yet supported.
- Not realising that named argument spread does not support reordering — array keys must match, not positions.
- Mixing positional spread and named arguments in a way that creates ambiguity — keep them separate.
Code Examples
// Positional spread — fragile, order-dependent:
function createUser(string $name, string $email, int $role): User {}
$args = ['Alice', 'alice@example.com', 1];
createUser(...$args); // Breaks if param order changes
// Named spread — order-independent:
$args = ['email' => 'alice@example.com', 'name' => 'Alice', 'role' => 1];
createUser(...$args);$args = ['name' => 'Alice', 'role' => 'admin'];
$user = createUser(...$args); // spreads as named args