{"id":2264,"date":"2021-07-11T03:12:00","date_gmt":"2021-07-11T03:12:00","guid":{"rendered":"https:\/\/phptutorial.net\/?page_id=2264"},"modified":"2025-04-07T13:43:35","modified_gmt":"2025-04-07T13:43:35","slug":"php-type-hints","status":"publish","type":"page","link":"https:\/\/www.phptutorial.net\/php-tutorial\/php-type-hints\/","title":{"rendered":"PHP Type Hints"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn how to use PHP type hints to declare the types for function parameters and return values.<\/p>\n\n\n\n

Introduction to PHP type hints #<\/a><\/h2>\n\n\n\n

PHP is a dynamically typed language. When you define a function<\/a>, you don’t need to declare types for parameters<\/a>. For example:<\/p>\n\n\n

<?php<\/span>\n\nfunction<\/span> add<\/span>($x, $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add(1<\/span>,2<\/span>);\necho<\/span> $result; \/\/ 3<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The add()<\/code> function accepts two arguments and returns the sum of them. In this example, we pass two integers into the add()<\/code> function and get the result as an integer.<\/p>\n\n\n\n
If you pass two floating-point numbers into the add()<\/code> function, you’ll get the sum of the floats<\/a>, which is a floating-point number:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>($x, $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add(1.0<\/span>,2.5<\/span>);\necho<\/span> $result; \/\/ 3.5<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
More interestingly, you can pass an integer and a numeric string into the add()<\/code> function, it will return an integer:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>($x, $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add(1<\/span>,'2'<\/span>);\necho<\/span> $result; \/\/ 3<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
In this case, the add()<\/code> function implicitly coerces the numeric string '2'<\/code> into the integer 2<\/code> because of the +<\/code> operator. <\/p>\n\n\n\n
If PHP fails to coerce the string argument into an integer, it’ll issue an error. For example:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>($x, $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add('Hi'<\/span>,'There'<\/span>);\necho<\/span> $result;<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
Fatal error: Uncaught TypeError: Unsupported operand types: string + string in ...<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
You can use type hints to enforce the types for function parameters and return values.<\/p>\n\n\n\n
PHP type hints for function parameters #<\/a><\/h2>\n\n\n\n
The type hints ensure that PHP will check the type of a value at the call time and throw a TypeError<\/code> if there is a mismatch.<\/p>\n\n\n\n
To add a type hint to a parameter, you place a type in front of it like this:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> my_function<\/span>(type $param1, type param2, ...)<\/span> <\/span>{\n   \/\/ ...<\/span>\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The following defines the add()<\/code> function that accepts two integers:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>(int $x, int $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add(1<\/span>,2<\/span>);\necho<\/span> $result;  \/\/ 3<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
However, if you pass two floats, you’ll get the result as an integer:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>(int $x, int $y)<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\n$result = add(1<\/span>,2.5<\/span>);\necho<\/span> $result; \/\/ 3<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
In this case, PHP implicitly coerces 2.5<\/code> into an integer (2<\/code>) before calculating the sum. Therefore, the result is an integer.<\/p>\n\n\n\n
Note that PHP issued the following decprecation message:<\/p>\n\n\n
Deprecated: Implicit conversion from float 2.5<\/span> to int loses precision<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
PHP type hints for the function’s return value #<\/a><\/h2>\n\n\n\n
To specify a return value’s type for a function, you add the type after the function header like this:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> my_function<\/span>(type $param1, type $param2, ...)<\/span> : type<\/span> \n<\/span>{\n    \/\/ ..<\/span>\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The following example defines the add()<\/code> function that accepts two integers and returns an integer:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>(int $x, int $y)<\/span>: int<\/span>\n<\/span>{\n    return<\/span> $x + $y;\n}\n\necho<\/span> add(10<\/span>, 20<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Starting from PHP 7.0, if a function doesn’t return a value, you use the void<\/code> type. For example:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> dd<\/span>($data)<\/span>:void<\/span>\n<\/span>{\n    echo<\/span> '<pre>'<\/span>;\n    var_dump($data);\n    echo<\/span> '<\/pre>'<\/span>;\n    die<\/span>;\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The union type #<\/a><\/h2>\n\n\n\n
Starting from PHP 8.0, if a function returns a value of several types, you can declare it as a union type. For example:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> add<\/span>($x, $y)<\/span>: int<\/span> | float<\/span>\n<\/span>{\n    return<\/span> $x * $y;\n}\n\nvar_dump(add(10<\/span>, 20<\/span>));\nvar_dump(add(1.5<\/span>, 2.5<\/span>));<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
In this example, the add()<\/code> function returns an integer or a floating-point number, depending on the types of arguments.<\/p>\n\n\n\n
The mixed type #<\/a><\/h2>\n\n\n\n
If a function returns a value of many types, you can use the mixed<\/code> type. The mixed<\/code> type means one of several types. The mixed<\/code> type is equivalent to the following union type:<\/p>\n\n\n
object|resource|array<\/span>|string|int|float|bool|null<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The mixed<\/code> has been available since PHP 8.0.0.<\/p>\n\n\n\n
For example, the built-in function filter_var()<\/code> uses both union type (array|int<\/code>) and mixed<\/code> type as the type hints:<\/p>\n\n\n
filter_var(mixed $value, int $filter = FILTER_DEFAULT, array<\/span>|int $options = 0<\/span>): mixed<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The nullable type #<\/a><\/h2>\n\n\n\n
The following defines a function that accepts a string and returns the uppercase of that string:<\/p>\n\n\n
<?php<\/span>\n\n\nfunction<\/span> upper<\/span>(string $str)<\/span>: string<\/span>\n<\/span>{\n    return<\/span> strtoupper($str);\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
If you pass an argument of null, you’ll get an error:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> upper<\/span>(string $str)<\/span>: string<\/span>\n<\/span>{\n    return<\/span> strtoupper($str);\n}\n\n$str = null<\/span>;\necho<\/span> upper($str);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
Fatal error: Uncaught TypeError: Argument 1 passed to upper() must be of the type string, null given<\/code><\/span>Code language:<\/span> plaintext<\/span> (<\/span>plaintext<\/span>)<\/span><\/small><\/pre>\n\n\n
To fix this, you can make the $str<\/code> parameter nullable like this:<\/p>\n\n\n
<?php<\/span>\n\nfunction<\/span> upper<\/span>(?string $str)<\/span>: ?string<\/span>\n<\/span>{\n    if<\/span>($str != null<\/span>) {\n        return<\/span> strtoupper($str);\n    }\n\n    return<\/span> null<\/span>;\n         \n}\n\n$str = null<\/span>;\necho<\/span> upper($str);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The nullable type was introduced in PHP 7.1.<\/p>\n\n\n\n
PHP allows you to mark the type declarations and returns values as nullable by prefixing the type name with a question mark (?<\/code>).<\/p>\n\n\n\n
In the above example, we add the ?<\/code> to the string type of the $str<\/code> parameter. The ?string<\/code> allows you to pass a string argument or null. <\/p>\n\n\n\n
We also mark the return type string<\/code> with ?<\/code> to make the type of the return value nullable.<\/p>\n\n\n\n
Note that the mixed<\/code> type already includes the null type. Therefore, you don’t need to include nullable mixed like this:<\/p>\n\n\n
? mixed<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
If you do this, you’ll encounter an error.<\/p>\n\n\n\n
Summary #<\/a><\/h2>\n\n\n\n
    \n
  • Use PHP type hints for function parameters and return types.<\/li>\n\n\n\n
  • Use void<\/code> type if the function doesn’t return any value.<\/li>\n\n\n\n
  • Use mixed<\/code> type or union type if function parameter or function return value expect several types.<\/li>\n\n\n\n
  • To make a type nullable, prefix the type with a question mark (?type<\/code>).<\/li>\n<\/ul>\n
    \n\t
    \n\t\t
    Did you find this tutorial useful?<\/div>\n\t\t
    \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t Yes <\/span>\n\t\t\t<\/button>\n\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t No <\/span>\n\t\t\t<\/button>\n\t\t<\/div>\n\t<\/header>\n\n\t
    \n\t\t
    \n\t\t\t
    <\/div>\n\t\t\t\n\t\t\t
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
By default, PHP coerces a value of the compatible type into the expected scalar type declaration if possible. To enforce the value with a type that matches the type declaration, you must declare strict typing<\/a>.<\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
In PHP 5, you can use array<\/a><\/code>, callable<\/code>, and class<\/a> for type hints. In PHP 7+, you can also use scalar types such as bool<\/code>, float<\/code>, int<\/code>, and string<\/code>.<\/p>\n\n\n\n
PHP also allows you to use type hints for class properties and methods which you’ll learn in the PHP object-oriented programming tutorial<\/a>.<\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n