[TASK] Add PHPStan extension to allow assertions

[JakeQZ]

Suppress warnings for assert()s that, according to the DocBlock, can never fail, but in reality could, due to programmer error, since the DocBlock types are not enforced by PHP.

This allows us to retain treatPhpDocTypesAsCertain:true for stricter static analysis, whilst also using assertions for runtime checks in a development environment, without cluttering up the code with @phpstan-ignore comments.

This change reverts and replaces #1622.

[coveralls]

coverage: 98.282% (+0.03%) from 98.252% — task/allow-assert-instanceof into main

[JakeQZ]

Got some helpful pointers from some kind folk in response to phpstan/phpstan#14616.

Not sure about the location and namespace of the extension class (file).

Also, I read some suggestions that PHPStan extensions should have a corresponding TestCase. So that may be needed as part of this PR, once we've agreed on locations and namespaces.

Looking for initial comments and feedback on this, rather than merging right now...

[JakeQZ]

Catering for

if ($impossibleConditionAccordingToDocBlock) {
    throw \Exception();
}

looks quite challenging...

[oliverklee]

Concerning the location: I'd say we put this in src/PHPStan/ and block this directory from export using .gitattributes. Then we can do over coverage magic (and later: infection and fuzzing magic) on this class as well.

The class then also needs to be @internal.

[oliverklee]

Also, we might consider moving this to a separate repo & package at some point in time so we can reuse it in PHP-CSS-Parser.

[oliverklee]

As far as the code is concerned, this already looks quite good to me!

[JakeQZ]

Concerning the location: I'd say we put this in src/PHPStan/ and block this directory from export using .gitattributes.

Done.

The class then also needs to be @internal.

Done.

Also, we might consider moving this to a separate repo & package at some point in time so we can reuse it in PHP-CSS-Parser.

I took this challenge on as a break from my paid work. Then sort-of wished I hadn't. But I think it was a decent learning curve, with a result that is potentially reusable, at least as an example.

Also, I read some suggestions that PHPStan extensions should have a corresponding TestCase. So that may be needed as part of this PR

I dug into this and have added tests.

[JakeQZ]

@oliverklee request-review

[ondrejmirtes]

This line ignores everything, not just the specified identifier

[JakeQZ]

Thanks for spotting that. It seems we have been using @phpstan-ignore-next-line in several places where we should have @phpstan-ignore, which also only ignores warnings from the next line, but allows (requires) a warning type parameter to narrow down which warnings should be suppressed.

[JakeQZ]

#1628 for the other cases.

[oliverklee]

I'd like to have this for our sister project as well. Should I port it, or would you be willing (or like) to do it, @JakeQZ ?