func_get_arg
Returns a single argument passed to the current function, selected by zero-based position.
func_get_arg(int $position): mixed- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$position | int | The zero-based offset of the argument to return. |
Return value
mixedThe argument at the given position in the current function's argument list.
Errors
Throws an Error when called from the global scope or invoked dynamically, and a ValueError if position is negative or greater than or equal to the number of arguments passed.
Changelog
- PHP 8.0Named arguments are treated as if passed positionally, and parameters that were not supplied are filled in with their declared defaults.
- PHP 8.0An out-of-range position now throws a ValueError; previously a warning was raised and false returned.
- PHP 7.0Current values are returned for by-value arguments, so a later reassignment of the parameter variable is visible here.
func_get_arg() reads one argument out of the argument list of the function it is called from, including arguments that were never declared as parameters. It is the single-value counterpart of func_get_args().
When to reach for it
Rarely, in modern code. Declared variadics (function f(int ...$nums)) cover almost every case more clearly, with type checks and IDE support. The one place func_get_arg() still shows up is maintenance work on older APIs that accept a loose, undeclared argument list, and in shim layers that must inspect one specific slot without materialising the whole array.
The PHP 8 behaviour to know
Since PHP 8, named arguments are normalised as if they had been passed positionally, and parameters you did not supply are filled in with their declared defaults. So a function with three defaulted parameters called with only a named third argument still reports three arguments, and func_get_arg(0) returns the default rather than throwing.
Out-of-range access is no longer a soft failure: PHP 8 throws a ValueError rather than returning false. Check func_num_args() first, or catch it.
Example
When to use it
- Reading one specific slot from a legacy function that accepts an undeclared argument list
- Writing a compatibility shim that inspects the third argument only when it was actually passed
- Building a debug helper that reports a single argument without copying the whole list
Frequently asked questions
What is the difference between func_get_arg and func_get_args?
func_get_arg() returns one argument at a given position, while func_get_args() returns the whole list as an array. Use the array form unless you genuinely only need one slot.
Why does func_get_arg throw a ValueError?
Because the position you asked for is negative or is not less than the number of arguments actually passed. Check func_num_args() before the call, or catch the ValueError.
Can I use func_get_arg with variadic parameters?
Yes, but there is no reason to. A declared variadic like function f(...$args) gives you the same values as a typed array, with better readability and static analysis.
More examples
Out-of-range access throws in PHP 8
The first call prints got: 'hello'. The second prints the ValueError message about the position needing to be less than the number of arguments passed. On PHP 7 that second call would have emitted a warning and returned false instead.
<?php
function firstOrNote(): string
{
try {
return 'got: ' . var_export(func_get_arg(0), true);
} catch (ValueError $e) {
return 'ValueError: ' . $e->getMessage();
}
}
echo firstOrNote('hello'), "\n";
echo firstOrNote(), "\n";Defaults are filled in for skipped parameters
Prints '3 args, slot 0 = A' then '1 args, slot 0 = one'. Passing c by name makes PHP normalise the call to three positional arguments with a and b taking their defaults, which is why slot 0 exists at all in the first call.
<?php
function slot(string $a = 'A', string $b = 'B', string $c = 'C'): string
{
return func_num_args() . ' args, slot 0 = ' . func_get_arg(0);
}
echo slot(c: 'see'), "\n";
echo slot('one'), "\n";By-value arguments report their current value
Prints 'before=shift after=SHIFT'. Since PHP 7 these functions read the live parameter variable, not a snapshot taken at call time, so reassigning the parameter changes what you get back. Capture the value first if you need the original.
<?php
function mutate(string $word): string
{
$before = func_get_arg(0);
$word = strtoupper($word);
$after = func_get_arg(0);
return "before=$before after=$after";
}
echo mutate('shift'), "\n";
Discussion