Quick overview on”Type hinting” in PHP

4 min readFeb 18, 2023

PHP is a dynamically typed language. When you write a code you don’t need to declare types for function parameters, return types and others.

But in my opinion it is strongly recommended to do that. The advantage of doing that is that your code is much more stable, cleaner and less error prone.

You can declare types with two mechanisms:

“Type hinting” which is a mechanism in programming language to specify the expected data type (arrays, objects, interface, etc.) for function parameters, for function return and other

“PHPDoc” is an informal standard for commenting PHP code, but it is in the process of being formalized. It does the same job as “Type hinting” but is more flexible and covers more cases.

function doSomething(User $user){
    //
}

In the above example we defined doSomething function which expects that first parameter should be a type of User class and that is defined with the “Type hinting”

/**
* @param User $user
*/
function doSomething($user){
    //
}

In the above example we defined doSomething function which expects that first parameter should be a type of User class and that is defined with the “PHPDoc”

There are a few popular packages which will analyze your PHP code and report what is violated. These packages usually have ability to set a level which violations will be reported.

“PHPStan” is one of the most popular packages for code analysing in PHP an it will analyze your code based on “Type hinting” and “PHPDoc” and will, among others, tell you two things:

If all parameters, return types and other things have defined type
If some defined types are violated. For example, parameter of the function is defined as int and you pass a string, See example below:

function doSomething(int $number){
    //
}

doSomething("some string");

It is a way better to define types with “Type hinting” rather than with “PHPDoc” when it is possible, here are some reasons:

With “Type hinting” your code is safer, because an error will be thrown during a runtime, if you pass different type than is declared in the method.
With PHPDoc your IDE and code analyzer like PHPStan will be able to detect and report those wrong passing parameters while analyzing code, but the error will not be thrown at the runtime.
If you have a lower level of reporting for code analyzer violation of type defined with “PHPDoc” will not be even reported during a code check.
With “Type hinting” your code has less lines which make is cleaner.

In PHP most recent versions (7.4 and 8) you can define a lot of things with the “Type hinting”, but there are also many cases when you can’t and only in that case you should use “PHPDoc”.

I have many times saw a code like this in these two examples:

/**
* @param User $user
*/
function doSomething($user){
    //
}

/**
* @param User $user
*/
function doSomething(User $user){
    //
}

In the #1 case you have defined a parameter type with PHPDoc but that is possible and better to define with “Type hinting”.
In the #2 case you are duplicating the same behaviour in the PHPDoc which is already defined with “Type hinting”

The correct solution for above #1 and #2 cases is:

function doSomething(User $user){
    //
}

Now you have defined a parameter with “Type hinting” and nothing is duplicated. Your code is clean and stable as much as possible.

Like we said before, you can’t express and cover all cases with the “Type hinting”, one of the examples where you cannot define type hint is an array of objects:

function doSomething($users){
    //
}

$users[] = $usersOne;
$users[] = $usersTwo;

doSomething($users);

“Type hinting” for that case is still not covered in the PHP, although there are some workarounds, which I would not recommend to do.
Reason why it is not covered is a performance, because the PHP then need to check every item of array during a runtime, and that can be a problem for big arrays.

“Type hinting” in the PHP would look like this:

function doSomething(array<User> $users){
 
}

But that is not possible in the current version in PHP, and will be probably also impossible in the next versions of the PHP due to performance issue.

So in that case you should use PHPDoc like this:

/**
* @param array<User> $users
*/
function doSomething($users){
    //
}

Also when you have two parameters, one which can be defined with “Type hinting” and one which can not you should define with “PHPDoc” only a parameter which can not be defined with “Type hinting”

/**
* @param array<User> $users
*/
function doSomething($users, int $number){
    //
}

Conclusion

“Type hinting” and “PHPDoc” are mechanism to define types of function parameters, return types and other in PHP

I strongly recommend to define all parameters, return types and other with “Type hinting” where it is possible and with “PHPDoc” where it is not.

You can use tools like PHPStan which will report you if you call some function with parameters different than is defined and other.

Quick overview on”Type hinting” in PHP

Written by Filip Horvat