PHP type hinting - code vs. annotations

Question

PHP 5 can do some (limited) type hinting, however, it seems to me that in real-world projects, types are usually described in doc comments. For example, instead of this:

/**
 * Test method
 */
function test(SomeType $param1) {
    ...
}

there will more commonly be

/**
 * Test method
 *
 * @param SomeType param1
 */
function test($param1) {
    ...
}

What are the advantages and disadvantages of the two approaches? And if I'm right in the assumption that the PhpDoc method is more common, why is that? Why don't people utilize the built-in language feature more?

Edit: the third option is to use both approaches combined:

/**
 * Test method
 *
 * @param SomeType param1
 */
function test(SomeType $param1) {
    ...
}

However, I personally haven't seen this used too often (looked at libraries like Symfony or PHPUnit) and this also seems like doing some work for not much additional benefit to be honest. Maybe that's why it isn't seen more often.

In the first, you can wirte @param SomeType $param1 also. And it prevents you to pass any other type of type than SomeType. Second will only show you it in the phpDoc, but $param1 could be any type. — vaso123
– vaso123, Commented Dec 19, 2014 at 10:54
If you're using an IDE with auto complete, you can also type hint inline, which comes in handy from time to time: /* @var $somevar \YourNamespace\YourObject */ — Jon
– Jon, Commented Dec 19, 2014 at 11:02
For the record: PHP has evolved. Its newer versions have much more powerful hinting capacities (can do scalars, arrays return types, nulls...). — Martin Grey
– Martin Grey, Commented Oct 11, 2018 at 15:18

Xwtek · Accepted Answer · 2020-05-05 05:12:04Z

4

First thing: PHP typehints have different ability to hint than PHPDoc. Differences are (at least):

Scalar types. Before PHP 7.1, you can not hint scalar types, while nothing prevents you from hinting
```
/**
 * @param string $param Param description
 */
```
Array of hinting. In PHPDoc you can hint, that parameter (or return value) is array of something. It would be:
```
/**
 * @param ClassName[] $param Param description
 */
```
and meaning of this is - array of instances of ClassName. This is extremely useful when it comes to return type (because IDE then may do substitutions for methods on iteration of that array, and, therefore, you'll know that you're doing correct thing or not). However, in PHP you can only typehint it as
```
function functionName(array $param) { /*...*/ }
```
so it won't be possible to realize what are actual elements of array. For your information there is a corresponding RFC for typehinting as array of some elements, which is currently rejected - but may be in future such possibility will appear in PHP.

But, on the other hand, using PHP typehints is still different thing and normally you should do both - so, if it's possible to hint somehow in PHP (like for array sample above) - do it, and add PHPDoc block as well. PHP typehint allows you to enforce behavior on language level, while PHPDoc is only "information" source, it serves only information goal and can not prevent of passing illegal argument type.

edited May 5, 2020 at 5:12

Xwtek

1,3111 gold badge11 silver badges19 bronze badges

answered Dec 19, 2014 at 10:58

Alma Do

37.4k10 gold badges81 silver badges106 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Borek Bernard Over a year ago

Good points, I'm just not sure about the last paragraph. While theoretically it certainly feels better to have both types of type hints it doesn't probably add too much value in practice, at least that's the way I see it and if you look at real-world projects out there it seems that I am not alone.

Alma Do Over a year ago

But it adds. If you have array of some instances, you will typehint it in PHP and in PHPDoc, so you, at least, won't be able to pass non-array to function (on language level), and, on the other hand, you'll be able to use IDE substitutions. So - yes, PHP typehints are limited, but you should use them as much as it's possible to narrow incoming parameter type, if you know the context of that

ashnazg Over a year ago

Actual enforcement of types at execution time is the reason to put typehints in the code itself. Putting it in the PHPDoc is common practice, mostly because PHPDoc predates PHP typehinting, and thus having a type documented by PHPDoc was the best you could do way back then with regard to a user knowing what the code expects. Doc generators will usually presume that the PHPDoc info is The True Info and use it, though they will also fall back to the code itself if PHPDoc is not given. IDEs usually follow the same behavior.

nbro Over a year ago

This answer needs to be updated so that it clearly states what is possible with what for different PHP versions. Isn't now possible to have array as the type hint for the return value?

gellu · Accepted Answer · 2014-12-19 10:57:15Z

0

Personally I would use both.

First option is good for controling what objects are you passing to the method. Second usually can be added automaticaly by any modern IDE and it makes your code more readable.

answered Dec 19, 2014 at 10:57

gellu

1345 bronze badges

Collectives™ on Stack Overflow

PHP type hinting - code vs. annotations

2 Answers 2

4 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

4 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related