Unless you tell the PHP engine otherwise, function arguments and return values don’t have any constraints on their types or values. The countdown() function in Example 5-9 assumes that its argument is a number, but you could pass a string such as “Caramel” as an argument and the PHP engine wouldn’t complain.
Type declarations are a way to express constraints on argument values. These tell the PHP engine what kind of value is allowed for an argument so it can warn you when the wrong kind is provided. Table 5-1 shows the different kinds of declarations the PHP engine understands and what version of PHP introduced support for them.
When defining a function, the type declaration goes before the argument name. Example 5-24 shows the function from Example 5-9 with the appropriate int type declaration in place.
Example 5-24. Declaring an argument type
function countdown(int $top) {
while ($top > 0) {
print “$top..”;
$top–;
}
print “boom!\n”;
}
$counter = 5;
countdown($counter);
print “Now, counter is $counter”;
The only difference between Example 5-9 and Example 5-24 is the int after countdown( and before $top. When countdown() is passed a valid integer (such as 5), the code runs just fine. If another type of value is passed, then the PHP engine complains. For example, if you call countdown(“grunt”); when using PHP 7, then you get an error message similar to:
PHP Fatal error: Uncaught TypeError: Argument 1 passed to countdown()
must be of the type integer, string given, called in decl-error.php
on line 2 and defined in countdown.php:2
Stack trace:
#0 decl-error.php(2): countdown(‘grunt’)
#1 {main}
thrown in countdown.php on line 2
In the error message, the PHP engine tells you about a TypeError, indicating which argument (1) passed to which function (countdown()) had a type mismatch, including what the argument type was supposed to be (integer) and what the argument type actually was (string). You also get information about where the problematic function call is and where the called function is defined.
In PHP 7, that TypeError is an exception that can be caught with an exception handler. “Indicating a Problem with Exceptions” on page 108 provides details on how to catch exceptions in your program.
PHP 7 also supports type declarations for the kind of value a function returns. To enforce checking of the return type of a function, put a : after the ) that closes the argument list, and then the return type declaration. For example, Example 5-25 shows the restaurant_check() function from Example 5-26 augmented with a return type declaration.
Example 5-25. Declaring a return type
function restaurant_check($meal, $tax, $tip): float {
$tax_amount = $meal * ($tax / 100 );
$tip_amount = $meal * ($tip / 100 );
$total_amount = $meal + $tax_amount + $tip_amount;
return $total_amount;
}
If the function in Example 5-25 returns anything but a float, the PHP engine generates a TypeError.
Source: Sklar David (2016), Learning PHP: A Gentle Introduction to the Web’s Most Popular Language, O’Reilly Media; 1st edition.