Variadic parameters

suggest change

A variadic function is a function that accepts an arbitrary number of arguments. In PHP 5.6 and later, variadic parameters are declared using the ellipsis / splat operator (...). In PHP 7 and 8, variadic parameters support strict type declarations, references, argument unpacking, and named arguments.


1. Syntax and Basic Usage

Prefixing a parameter name with ... indicates that the function accepts zero or more trailing arguments. The interpreter collects all matching arguments into a standard PHP array:

<?php

function sum(int ...$numbers): int
{
    $total = 0;
    foreach ($numbers as $num) {
        $total += $num;
    }
    return $total;
}

echo sum(1, 2, 3), "\n";          // Output: 6
echo sum(10, 20, 30, 40), "\n";   // Output: 100
echo sum(), "\n";                 // Output: 0 (Empty array)

Mixing Fixed and Variadic Parameters

A function can have regular positional parameters before the variadic parameter. The variadic parameter must always be the last parameter in the signature:

<?php

function logEvent(string $level, string $context, string ...$messages): void
{
    $timestamp = date('Y-m-d H:i:s');
    $joined = implode(' | ', $messages);
    echo "[$timestamp] [$level] ($context): $joined\n";
}

logEvent('INFO', 'AuthService', 'User 42 logged in', 'IP: 192.168.1.1', '2FA verified');
// Output: [2026-10-17 17:30:00] [INFO] (AuthService): User 42 logged in | IP: 192.168.1.1 | 2FA verified

2. Type Hinting Variadic Parameters

When a type hint is declared for a variadic parameter, every individual argument passed to it must satisfy that type:

<?php

declare(strict_types=1);

class User
{
    public function __construct(public string $name) {}
}

function registerUsers(User ...$users): void
{
    foreach ($users as $user) {
        echo "Registering: " . $user->name . "\n";
    }
}

$u1 = new User("Alice");
$u2 = new User("Bob");

registerUsers($u1, $u2); // Valid

// Passing an invalid type raises a TypeError:
// registerUsers($u1, "Charlie"); // TypeError: registerUsers(): Argument #2 must be of type User, string given

You can also use union types or nullable types:

function processItems(int|float ...$values): float
{
    return array_sum($values);
}

3. Passing by Reference (&...$params)

Variadic parameters can be passed by reference by placing & before ...:

<?php

function addPrefix(string $prefix, string &...$strings): void
{
    foreach ($strings as &$str) {
        $str = $prefix . $str;
    }
}

$greeting1 = "world";
$greeting2 = "PHP";

addPrefix("Hello, ", $greeting1, $greeting2);

echo $greeting1 . "\n"; // Output: Hello, world
echo $greeting2 . "\n"; // Output: Hello, PHP

4. Argument Unpacking (The Spread Operator)

The ellipsis operator also acts as the spread / unpack operator when calling a function. It unpacks an array or any Traversable object into discrete arguments:

<?php

function calculateDiscount(float $basePrice, float $rate, float $coupon): float
{
    return ($basePrice * (1 - $rate)) - $coupon;
}

$params = [100.0, 0.20, 5.0];

// Unpacks array elements into positional parameters
echo calculateDiscount(...$params); // Output: 75

Unpacking Named Arguments (PHP 8.0+)

Since PHP 8.0, associative arrays can be unpacked into named arguments matching parameter names:

<?php

function configureConnection(string $host, int $port = 3306, string $charset = 'utf8mb4'): void
{
    echo "Connecting to $host:$port (charset: $charset)\n";
}

$config = [
    'host'    => 'db.internal',
    'charset' => 'utf8',
    'port'    => 3307,
];

// Automatically matches array keys to parameter names regardless of order:
configureConnection(...$config);
// Output: Connecting to db.internal:3307 (charset: utf8)

5. Modern ... vs. Legacy func_get_args()

Before PHP 5.6, variable-length arguments were handled using func_get_args(), func_num_args(), and func_get_arg():

// Legacy approach (PHP 5.5 and older):
function legacySum()
{
    $args = func_get_args();
    return array_sum($args);
}

Why Variadic ... is Superior

  1. Self-Documenting: The function signature explicitly indicates that variable arguments are accepted.
  2. Type Safety: Enforces type declarations per element (int ...$numbers).
  3. Reference Support: Supports pass-by-reference (&...$args), which func_get_args() cannot do.
  4. Performance: Avoids runtime function overhead to inspect execution frames.

Best Practices

  1. Always Type-Hint Variadic Parameters: Take advantage of strict typing (string ...$tags) to prevent unexpected types inside the array.
  2. Do Not Abuse Variadic Signatures for Structs: If a function requires diverse options, prefer an explicit Configuration DTO, associative array, or named parameters over an untyped variadic list.
  3. Remember Default Value: If a caller passes no variadic arguments, PHP assigns an empty array []—you do not need to check isset() or handle null.

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents