Are type declarations and type annotations outdated or complementary?

Question

I have always used annotations to declare a return type. For instance:

/** * @return SomeClass */ public function () { ... } 

But now I see a different way:

 public function () : SomeClass { ... } 

Question

Do I have to choose between them, using both, or do they have some fundamental difference that I should be aware of?

Answer 1

Annotations have nothing to do with the return type. It will not cause any errors or warnings if you return something else. Although it is useful for documentation.

In addition, another method is php7 declarations of the type of the returned file , which support all the same types as the arguments. To indicate the return type, we add a colon, and then the type immediately before the opening brace.

Strong typing also affects return type declarations. In weak mode, by default, return values ​​will be forced to the correct type if they are not already of this type. In strong mode, the return value must be of the correct type, otherwise a TypeError will be raised.

Adding a return type allows you to make sure your function returns the expected one, and also makes it easy to see how the function works.

NOTE.

When overriding the parent method, the child method must match any return type for the parent. If the parent does not determine the return type, then the child method can do this.

Answer 2

According to me, you should use both options whenever possible.

Adding a function return type to PHP (possibly from PHP 7) is useful for providing runtime type. Note that PHP 7 allows you to support the type of parameters in a function.

Adding the annotation function above is useful for creating documentation. Example PHPDocumentor uses annotation like @return .

Answer 3

There is some degree of overlap between them.

Unlike type annotations, type declarations are part of the language itself and are enforced at runtime. If you use a type declaration to indicate that the function accepts (or returns) an int , and you pass (or return) an array, you will receive an error message. If you pass a float, PHP will try to convert it for you, if possible, and otherwise, otherwise (weak mode) or always throw an error (strict mode). Type declarations are also checked in inheritance and in the implementation of interfaces, which prevents the use of incorrect types in your implementations. Annotations, on the other hand, are merely comments and are not executed at runtime. Since type declarations are enforced, you will ideally always use them wherever possible.

Because type annotations and type declarations can serve as documentation for a parameter or return type, the annotation is redundant if you have a type declaration. But keep in mind if you use tools like an IDE or a documentation generator that do not yet recognize type declarations, and you will need to keep annotations. You should also consider that you can provide a parameter description or return value in the annotation for documentation that you cannot do with the type declaration, and sometimes you can also specify a more precise type in the annotation (for example, an int[] declaration annotation vs array or subclass of the class returned by the method you override). However, if none of them apply, and your annotations do not contain more information than in the function signature ( function foobar(int $foo, string $bar): Qux string function foobar(int $foo, string $bar): Qux ), the annotations are a waste of space.

So, in summary: always use type declarations. As for annotations, use them if you need (equipment) or they provide additional information.