Do type declarations and type annotations obsolete or complement each other?

Question

I've always used annotations to declare return type. For example:

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

But now I see there's another way:

public function () : SomeClass { ... }

Question

Should I be choosing between these, using both, or do they have some fundamental difference I should be aware of?

Answer 1

According to me you should use both when possible.

Adding return type of function in PHP (possible from PHP 7) is useful to ensure type during execution. Note that PHP 7 allow supports parameters type in function.

Adding annotation above function is useful to generate documentation. Example PHPDocumentor uses annotation, like @return.

Answer 2

Annotation has nothing to do with return type. It will not throw any error or warning if you are returning something else. Although it's helpful for documentation.

Apart from that the other method is php7 Return Type Declarations which support all the same types as arguments. To specify the return type, we add a colon and then the type right before the opening curly bracket.

Strict typing also has an effect on return type declarations. In the default weak mode, returned values will be coerced to the correct type if they are not already of that type. In strong mode, the returned value must be of the correct type, otherwise a TypeError will be thrown.

Adding the return type allows you to to be sure your function returns what is expected as well as making it easy to see upfront how the function works.

NOTE :

When overriding a parent method, the child's method must match any return type declaration on the parent. If the parent doesn't define a return type, then the child method may do so.

Answer 3

There is some degree of overlap between these.

Unlike type annotations, type declarations are part of the language itself, and enforced by the language runtime. If you use a type declaration to specify that a function takes (or returns) an int, and you pass in (or return) an array, you'll get an error. If you pass in a float, PHP will try to convert it for you if possible and error otherwise (weak mode), or always throw an error (strict mode). Type declarations are also checked in inheritance and when implementing interfaces, preventing you using the wrong types in your implementations. Annotations, on the other hand, are merely comments and are not enforced by the runtime. Because type declarations are enforced, you would ideally always use them where possible.

Since both type annotations and type declarations can serve as documentation of a parameter or return type, an annotation is redundant if you have a type declaration. But bear in mind whether you are using tools, such as an IDE or documentation generator, that don't recognise type declarations yet, and would need you to retain the annotations. You should also consider that you can provide a description of a parameter or return value in an annotation for documentation, which you can't do with a type declaration, and there are also sometimes cases where you can specify a more precise type in an annotation (e.g. int[] annotation vs array declaration, or a subclass of the class returned by the method you are overriding). However, if neither of these apply, and your annotations provide no more information than is in the function signature (the function foobar(int $foo, string $bar): Qux line), annotations are a waste of space.

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