Constructors and destructors do not have the concept of a return type. The docs showing anything at all, even void, is incorrect.

> Constructors and destructors do not have the concept of a return
> type.

The same is true for some of the other magic methods (e.g.
__wakeup()).

True, but __wakeup allows for a void return type. Which I don't mind because its counterpart __sleep does have a return type.

To me it's more the fact that __construct/destruct are particularly special methods and explicitly disallow return types. __clone too, now that I look at the list.

I understand that some methods had always implicitly disallowed return values before there had been a syntax to do so explicitly. The hard syntax error certainly was proper before 7.1. 

However, this is 2018. Why would we still force occasional PHP users from having to memorize the signature for each and every magic method?

Now that "void" is a type hint, it seems that an author writing self-documenting code (for the benefit of less-versed coworkers) should not be penalized with run-time errors for explicitly defining VOID?

I respectfully suggest that with 7.1 and higher, the message category 
"... cannot declare a return type" 
should simply recognize the now-available type "void" as being a perfectly expression of the implicit rule!

https://www.google.com/search?q=why+dont+constructors+have+return+types

This isn't about method signatures. This is about what constructors, destructors, and cloning represent. The fact that PHP allows you to specify their behavior using a syntax that resembles that of normal methods is besides the point.

> using a syntax that resembles that of normal methods is besides the point.
Hmm, okay, poor choice of words there, but what I'm trying to say is that for these three methods return types do not make sense. Because there are no return values. Not in the sense of "this function isn't returning a value" but more "this function is incapable of using return values in the first place".

Other languages:

C# and Java don't have types.
> class Example { public Example() { } }

Python 3 does support a return type on __init__ but for reasons I don't quite understand.
https://www.python.org/dev/peps/pep-0484/#id13
> (Note that the return type of __init__ ought to be annotated with -> None. The reason for this is subtle. If
> __init__ assumed a return annotation of -> None, would that mean that an argument-less, un-annotated __init__ method
> should still be type-checked? Rather than leaving this ambiguous or introducing an exception to the exception, we
> simply say that __init__ ought to have a return annotation; the default behavior is thus the same as for other
> methods.)
I can't tell what ambiguity they're talking about, but I suspect it doesn't apply to PHP since return types are invariant.
(There's also __new__ but that's more of a factory method than a constructor.)

Meanwhile Ruby has constructors but no return types, and Perl has return types but no constructors.

> I can't tell what ambiguity they're talking about, but I suspect
> it doesn't apply to PHP since return types are invariant.

It seems to me this “ambiguity” is actually what this discussion
is about: if no return type annotation/declaration would be given,
should return statements be checked, or not?  In my opinion, it
does not make much sense, though, to make a constructor special so
that only a None/void return type annotation/declaration would be
accepted, rather than to make a constructor special by not
allowing to specify any return type annotation/declaration, in the
first place.

FWIW: JavaScript's constructor functions are a notable exception
to the no return type, since `new Foo` may return a `Bar`.

Anyhow, I don't think it is useful to have a lengthy discussion
here; the internals mailing list would be more suitable.

Actually, this discussion happend in the meantime[1], and while
declaring the return type of __clone() as void, the notion of
declaring return types for __construct() and __destruct() has been
declined for reasons[2].

This has been documented the magic methods[3]:

| If type declarations are used in the definition of a magic
| method, they must be identical to the signature described in this
| document. Otherwise, a fatal error is emitted. Prior to PHP 8.0.0,
| no diagnostic was emitted.

This doesn't properly cater to __construct() and __destruct(),
though.

[1] <https://externals.io/message/109542>
[2] <https://externals.io/message/109542#109638>
[3] <https://www.php.net/manual/en/language.oop5.magic.php>