Fix return type of loading DOM documents on PHP 8.0-8.2 branches.

[VincentLanglet]

Hi @nielsdos,

In #11803 you fixed the return type of loading DOM documents on PHP 8.3 branch.
I'd like to fix the PHPdoc too on PHP-8.0, PHP-8.1 and PHP-8.2 branch.

The https://github.com/phpstan/php-8-stubs library is generating stub/phpdoc directly from the four PHP-8.0, PHP-8.1, PHP-8.2 and PHP-8.3 branches and merging the results.
Unfortunately the fact that the phpdoc is wrong on PHP 8.0-8.2 branches ends with a wrong phpdoc on phpstan stubs
https://github.com/phpstan/php-8-stubs/blob/main/stubs/ext/dom/DOMDocument.php#L84

It would be great to fix the phpdoc too on 8.0 branch (and 8.1 and 8.2) to solve this phpstan issue.
phpstan/phpstan#10057 (comment)

I know PHP 8.0 is EOL, but does such PR would be ok ?

[nielsdos]

Hi

PHP 8.0 is EOL, and PHP 8.1 is in security-only-mode. So the lowest branch fixes can go into is PHP-8.2.
The type change in itself is correct: DOMDocument can't be returned since 8.0.
There is no problem accepting a change that changes the @return annotation in the phpdoc block, but I don't think we can add a tentative return in a stable release. Paging @kocsismate

[VincentLanglet]

PHP 8.0 is EOL, and PHP 8.1 is in security-only-mode. So the lowest branch fixes can go into is PHP-8.2. The type change in itself is correct: DOMDocument can't be returned since 8.0. There is no problem accepting a change that changes the @return annotation in the phpdoc block, but I don't think we can add a tentative return in a stable release. Paging @kocsismate

Do you means I should write

/** @return bool */
public function load(string $filename, int $options = 0) {}

rather than

/** @tentative-return-type */
public function load(string $filename, int $options = 0): bool {}

to have more chance to be accepted on the EOL branch ?

[nielsdos]

Do you means I should write

/** @return bool */
public function load(string $filename, int $options = 0) {}

That change would definitely not be a problem on PHP-8.2.
However, no changes are done on the EOL branch; and only security-related changes are done on the PHP-8.1 branch.

[kocsismate]

Yes, as Niels mentioned, the PR should target PHP 8.2, but new tentative return types shouldn't be added for existing releases for sure. You can definitely add regular PHPDoc comments, however I don't know how PHPStan parses them.

[VincentLanglet]

Yes, as Niels mentioned, the PR should target PHP 8.2, but new tentative return types shouldn't be added for existing releases for sure. You can definitely add regular PHPDoc comments, however I don't know how PHPStan parses them.

Unfortunately i'm afraid that if the phpdoc is not fixed on 8.0 and 8.1 too, phpstan will still believe it can returns DomDocument. I'll see what can be done on PHPStan side.

[VincentLanglet]

I'll still fix it on PHP-8.2 just in case #13763