Information may be passed to functions via the argument list, which is a comma-delimited list of expressions. The arguments are evaluated from left to right.
PHP supports passing arguments by value (the default), passing by reference, and default argument values.Variable-length argument lists are also supported.
Example #1 Passing arrays to functions
<?phpfunction takes_array($input)
{
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}?>Passing arguments by reference ¶
By default, function arguments are passed by value (so that if the value of the argument within the function is changed, it does not get changed outside of the function). To allow a function to modify its arguments, they must be passed by reference.
To have an argument to a function always passed by reference, prepend an ampersand (&) to the argument name in the function definition:
Example #2 Passing function parameters by reference
<?phpfunction add_some_extra(&$string)
{
$string .= 'and something extra.';
}$str = 'This is a string, ';add_some_extra($str);
echo $str; // outputs 'This is a string, and something extra.'?>Default argument values ¶
A function may define C++-style default values for scalar arguments as follows:
Example #3 Use of default parameters in functions
<?phpfunction makecoffee($type = "cappuccino")
{
return "Making a cup of $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("espresso");?>
The above example will output:
Making a cup of cappuccino. Making a cup of . Making a cup of espresso.
PHP also allows the use of arrays and the special type
NULL as default values, for example:
Example #4 Using non-scalar types as default values
<?phpfunction makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
{
$device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
return "Making a cup of ".join(", ", $types)." with $device.\n";
}
echo makecoffee();
echo makecoffee(array("cappuccino", "lavazza"), "teapot");?>
The default value must be a constant expression, not (for example) a variable, a class member or a function call.
Note that when using default arguments, any defaults should be on the right side of any non-default arguments; otherwise, things will not work as expected. Consider the following code snippet:
Example #5 Incorrect usage of default function arguments
<?phpfunction makeyogurt($type = "acidophilus", $flavour)
{
return "Making a bowl of $type $flavour.\n";
}
echo makeyogurt("raspberry"); // won't work as expected?>
The above example will output:
Warning: Missing argument 2 in call to makeyogurt() in /usr/local/etc/httpd/htdocs/phptest/functest.html on line 41 Making a bowl of raspberry .
Now, compare the above with this:
Example #6 Correct usage of default function arguments
<?phpfunction makeyogurt($flavour, $type = "acidophilus")
{
return "Making a bowl of $type $flavour.\n";
}
echo makeyogurt("raspberry"); // works as expected?>
The above example will output:
Making a bowl of acidophilus raspberry.
Type declarations ¶
Type declarations allow functions to require that parameters are of a certain type at call time. If the given value is of the incorrect type, then an error is generated: in PHP 5, this will be a recoverable fatal error, while PHP 7 will throw a TypeError exception.
To specify a type declaration, the type name should be added before the parameter name. The declaration can be made to accept
NULL values if the default value of the parameter is set to NULL.Valid types ¶
| Type | Description | Minimum PHP version |
|---|---|---|
| Class/interface name | The parameter must be an instanceof the given class or interface name. | PHP 5.0.0 |
| array | The parameter must be an array. | PHP 5.1.0 |
| callable | The parameter must be a valid callable. | PHP 5.4.0 |
| bool | The parameter must be a boolean value. | PHP 7.0.0 |
| float | The parameter must be a floating point number. | PHP 7.0.0 |
| int | The parameter must be an integer. | PHP 7.0.0 |
| string | The parameter must be a string. | PHP 7.0.0 |
Examples ¶
Example #7 Basic class type declaration
<?phpclass C {}
class D extends C {}
// This doesn't extend C.class E {}
function f(C $c) {
echo get_class($c)."\n";
}
f(new C);f(new D);f(new E);?>
The above example will output:
C
D
Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
thrown in - on line 8
Example #8 Basic interface type declaration
<?phpinterface I { public function f(); }
class C implements I { public function f() {} }
// This doesn't implement I.class E {}
function f(I $i) {
echo get_class($i)."\n";
}
f(new C);f(new E);?>
The above example will output:
C
Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
thrown in - on line 8
Example #9 Nullable type declaration
<?phpclass C {}
function f(C $c = null) {
var_dump($c);
}
f(new C);f(null);?>
The above example will output:
object(C)#1 (0) {
}
NULL
Strict typing ¶
By default, PHP will coerce values of the wrong type into the expected scalar type if possible. For example, a function that is given an integer for a parameter that expects a string will get a variable of type string.
It is possible to enable strict mode on a per-file basis. In strict mode, only a variable of exact type of the type declaration will be accepted, or a TypeError will be thrown. The only exception to this rule is that an integer may be given to a function expecting a float.
To enable strict mode, the declare statement is used with the strict_types declaration:
Example #10 Strict typing
<?phpdeclare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));var_dump(sum(1.5, 2.5));?>
The above example will output:
int(3)
Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
thrown in - on line 4
Example #11 Weak typing
<?phpfunction sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));
// These will be coerced to integers: note the output below!var_dump(sum(1.5, 2.5));?>
The above example will output:
int(3) int(3)
Example #12 Catching TypeError
<?phpdeclare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
try {
var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
} catch (TypeError $e) {
echo 'Error: '.$e->getMessage();
}?>
The above example will output:
int(3) Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10
Variable-length argument lists ¶
PHP has support for variable-length argument lists in user-defined functions. This is implemented using the ...token in PHP 5.6 and later, and using the func_num_args(), func_get_arg(), and func_get_args() functions in PHP 5.5 and earlier.
... in PHP 5.6+ ¶
In PHP 5.6 and later, argument lists may include the ... token to denote that the function accepts a variable number of arguments. The arguments will be passed into the given variable as an array; for example:
Example #13 Using ... to access variable arguments
<?phpfunction sum(...$numbers) {
$acc = 0;
foreach ($numbers as $n) {
$acc += $n;
}
return $acc;
}
echo sum(1, 2, 3, 4);?>
The above example will output:
10
You can also use ... when calling functions to unpack an array or Traversable variable or literal into the argument list:
Example #14 Using ... to provide arguments
<?phpfunction add($a, $b) {
return $a + $b;
}
echo add(...[1, 2])."\n";
$a = [1, 2];
echo add(...$a);?>
The above example will output:
3 3
You may specify normal positional arguments before the ... token. In this case, only the trailing arguments that don't match a positional argument will be added to the array generated by ....
It is also possible to add a type hint before the ... token. If this is present, then all arguments captured by ... must be objects of the hinted class.
Example #15 Type hinted variable arguments
<?phpfunction total_intervals($unit, DateInterval ...$intervals) {
$time = 0;
foreach ($intervals as $interval) {
$time += $interval->$unit;
}
return $time;
}
$a = new DateInterval('P1D');$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';
// This will fail, since null isn't a DateInterval object.echo total_intervals('d', null);?>
The above example will output:
3 days Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2
Finally, you may also pass variable arguments by reference by prefixing the ... with an ampersand (&).
Older versions of PHP ¶
No special syntax is required to note that a function is variadic; however access to the function's arguments must use func_num_args(), func_get_arg() and func_get_args().
The first example above would be implemented as follows in PHP 5.5 and earlier:
Example #16 Accessing variable arguments in PHP 5.5 and earlier
<?phpfunction sum() {
$acc = 0;
foreach (func_get_args() as $n) {
$acc += $n;
}
return $acc;
}
echo sum(1, 2, 3, 4);?>
The above example will output:
10
No comments:
Post a Comment