Что такое named arguments в PHP 8 и как они улучшают читаемость кода?

Named arguments в PHP 8

Named arguments (именованные аргументы) — возможность передавать значения в функцию по имени параметра, а не по позиции. Синтаксис: имя_параметра: значение. Доступны с PHP 8.0.

Базовый синтаксис

<?php

function createUser(
    string $name,
    int $age = 18,
    string $role = 'user',
    bool $active = true
): array {
    return compact('name', 'age', 'role', 'active');
}

// Без named arguments — нужно помнить порядок
$user1 = createUser('Alice', 18, 'user', false);

// С named arguments — пропускаем дефолтные, меняем порядок
$user2 = createUser(
    name: 'Bob',
    active: false,
    role: 'admin'
);

print_r($user2);
// ['name' => 'Bob', 'age' => 18, 'role' => 'admin', 'active' => false]

Применение со встроенными функциями

Named arguments особенно полезны при вызове встроенных PHP-функций с многочисленными параметрами.

<?php

// array_slice: без named args нужно помнить порядок
$arr = [1, 2, 3, 4, 5];

// Старый способ — четвёртый аргумент preserve_keys трудно заметить
$slice1 = array_slice($arr, 1, 3, true);

// С named arguments — намерение очевидно
$slice2 = array_slice(
    array: $arr,
    offset: 1,
    length: 3,
    preserve_keys: true
);

// htmlspecialchars с явными флагами
$safe = htmlspecialchars(
    string: '<script>alert(1)</script>',
    flags: ENT_QUOTES | ENT_HTML5,
    encoding: 'UTF-8'
);

// str_contains, str_starts_with — самодокументирующийся код
$result = str_contains(haystack: 'Hello World', needle: 'World');

Named arguments в атрибутах PHP 8

<?php

use Symfony\Component\Routing\Annotation\Route;

class UserController
{
    #[Route(path: '/users', name: 'user_list', methods: ['GET'])]
    public function list(): Response
    {
        // ...
    }
}

Комбинирование позиционных и именованных аргументов

<?php

function logMessage(string $level, string $message, array $context = []): void
{
    echo "[$level] $message";
}

// Позиционный первый, именованный третий — допустимо
logMessage('error', 'Something failed', context: ['user_id' => 42]);

// НЕЛЬЗЯ: именованный перед позиционным для того же параметра
// logMessage(level: 'error', 'Something failed'); // Fatal error

Использование с spread-оператором

<?php

function render(string $template, string $theme = 'default', bool $cache = true): string
{
    return "$template-$theme-" . ($cache ? 'cached' : 'fresh');
}

$args = ['theme' => 'dark', 'cache' => false];
echo render('home', ...$args);
// home-dark-fresh

Подводные камни

• Переименование параметров ломает API — если вы используете named arguments при вызове чужой библиотеки, переименование параметра в новой версии библиотеки вызовет Fatal error: Unknown named argument.
• Нельзя дублировать аргументы — передача параметра и позиционно, и по имени одновременно вызывает фатальную ошибку.
• Именованные аргументы нельзя ставить до позиционных — порядок нарушать допустимо только если все обязательные позиционные идут первыми.
• Не работают с устаревшими расширениями — некоторые внутренние функции в старых PECL-расширениях могут не иметь именованных параметров в отражении (ReflectionExtension).
• Variadic-параметры не поддерживают named — передача именованного аргумента в ...$args помещает его в ассоциативный массив, что может сломать логику обработки.
• Магические методы __call и __callStatic — named arguments не передаются по имени в $arguments, только значения; имена теряются.
• Производительность при анализе кода — статические анализаторы (Psalm, PHPStan) требуют актуальных стабов для корректной проверки; устаревшие стабы дают false-positive ошибки.

• Сводить named arguments к названию метода без lifecycle и failure path.
• Игнорировать модель runtime: интерпретируемый runtime PHP 8.x, обычно запускаемый как отдельный запрос в FPM, CLI или worker-процессе.
• Не отделять validation, authorization, transaction boundary и business logic.

• Объясняет named arguments через конкретную точку lifecycle в PHP.
• Приводит корректный минимальный пример без вымышленных методов или callbacks.
• Называет edge cases: пустые значения, ошибки, транзакции, безопасность или concurrency.