Fix handling of $this return type in UnionTypes rule

[simPod]

$this refers to the exact object identity, not just the same type. Therefore, it's valid and should not be removed
@see https://wiki.php.net/rfc/this_return_type for more context

Fixes #1246

[TomasVotruba]

The RFC targets PHP 8.2 and the voting did not yet started. We always way for the feature to be at least merged to PHP core before we apply the language. Sometimes the proposal can be denied and then Rector would work with non-existing feature.

[simPod]

The proposal is about adding a native typehint but $this lives in phpdoc since I've started the php and have always meant the same thing.

The $this return type follows an established convention from PHPDoc, where @return $this is commonly used in place of @return static where it comes to fluent interfaces. On a dataset of 2k composer packages, @return $this occurs 29k times, while @return static is used 38k times.

The $this return type is arguably not a type, in that enforces not just the type of the return value (which is the same as static), but also its object identity (that of $this). The object identity is important to the usage of the API, because it determines whether the return value can be safely discarded

I have added the RFC link for more context but it is not really relevant, whether it will be accepted or not since it only introduces $this natively.

[TomasVotruba]

This fixture is correct. In case of final class, the doc is exact duplicate of self.
We've removed many of these cases manually, that's why this rule handled it.

[simPod]

But self !== $this. Correct me if I'm wrong but the proper usage and difference is:

For mutable withers, you'd use $this. For immutable withers, you'd use self.

final class A
{
    public function withMute(): self
    {
        return clone $this;
    }

    /**
     * @return $this
     */
    public function withNoMute(): self
    {
        return $this;
    }
}

We've removed many of these cases manually, that's why this rule handled it.

So it depends what were your cases. If you had mutable withers, those should not have been removed AFAIK.

[TomasVotruba]

It depends how PHPStan handles these 2 cases, as we depend on its type system. Is it same or different from PHPStan view?

The change might be needed there.

[simPod]

I'd it does not care about that https://phpstan.org/r/54c6b6d0-1979-4ee6-9a62-927bc10317c1

[simPod]

But even though phpstan might not distinguish between that, the union rule should not touch it. 🤔

[TomasVotruba]

Thanks for checking and I agree with you.

But in that case it must be resolved there first. Then we can use it here.

[simPod]

But in that case it must be resolved there first. Then we can use it here.

Shouldn't this #1246 be reverted then? It's not working properly, I'd say there's a bug in behaviour now.

[simPod]

@TomasVotruba BTW just found out PHPStan already supports it.

Method SimPod\GraphQLUtils\Builder\InputObjectBuilder::create() should return $this(SimPod\GraphQLUtils\Builder\InputObjectBuilder) but returns static(SimPod\GraphQLUtils\Builder\InputObjectBuilder)