DOM methods do not provide a return type for ReflectionMethod

[JoshyPHP]

Description

DOM methods do not provide a return type when inspected via ReflectionMethod. I'm not sure whether it's by design, an oversight, or a bug. The DOM stub has return type annotations but no actual return type. As far as I can tell, DOM properties can be inspected normally too.

The following code:

<?php declare(strict_types=1);

$class    = new ReflectionClass('DOMDocument');
$method   = $class->getMethod('createElement');
$property = $class->getProperty('documentElement');
var_dump(
	phpversion(),
	$method->getReturnType(),
	$method->getTentativeReturnType(),
	$property->getType()->getName()
);

Resulted in this output:

string(8) "8.3.0RC4"
NULL
NULL
string(10) "DOMElement"

But I expected this output instead:

string(8) "8.3.0RC4"
object(ReflectionNamedType)
NULL
string(10) "DOMElement"

PHP Version

8.1.24, 8.2.11, 8.3.0RC4

Operating System

No response

[nielsdos]

Hi

The return type annotations don't enforce the type, while a return type declaration would.
This is chosen like that by design, I'll explain:

The DOM classes can be extended by user classes. This means that user classes can also override methods provided by the DOM classes. Back in the day, return type declarations weren't a thing, so overridden methods could have a different return type. When we enforce the return types, the overridden methods must have the same, or narrower return type. To avoid breakage when these return types were introduced, the return types aren't declared yet.

I suppose we could make them tentative though. This would not strictly enforce the return types, but issue a warning if it's violated. This would make the return types available in reflection (via getTenativeReturnType), but not strongly enforce them.
/cc @kocsismate what are your thoughts?

[JoshyPHP]

Extending DOM classes is indeed what I'm doing at the moment and I can see how return types could complicate things for others.

For context, I'm looking into reflection to generate my own annotations for static analysis purposes, so that analysers know that DOMDocument::createElement() will return my custom class rather than a DOMElement. Having a tentative return type satisfies my needs, for what is admittedly quite a fringe case.

[kocsismate]

The reason some of the DOMDocument methods don't have a tentative return type is that their return type is not conformant to the DOM spec. You can see more context in the PR where I added the tentative return types: #6985 (especially here: #6985 (comment) and here: #6985 (comment))

[nielsdos]

Thanks for the answer, that makes sense. The false union for strictness is unfortunate... So we can't make any changes unless we decide what to do with strict error checking, because otherwise we're stuck with it basically forever.

[nielsdos]

I decided what to do with this.

We can't get rid of strict error checking, I searched and found this is used way too much.
Furthermore, even if we fix inconsistencies caused by strict error checking, there are other inconsistencies caused by the existence of DOMNameSpaceNode.
So this issue is unfixable for BC reasons.

However, I'm currently working on a backwards compatible improvement on the DOM extension that will introduce new classes in a separate namespace. See https://externals.io/message/122048
As the issue will not be present for those new classes, I'm closing this as "won't fix".