Exceptions declared on interfaces unused in implementations reported as unused

[Majkl578]

There seem to be false positives with exceptions declared on interface methods that are not being used in the method implementation. This seems to be due to merging phpDoc since PHPStan 0.12.24 (phpstan/phpstan-src#196). Happens both in 0.10.1 and 0.11.0.

interface Foo {
    /**
     * @throws SomeException
     */
    function bar(): void;
}

class SomeFoo implements Foo {
    public function bar(): void
    {
        // no throw here -> causes Unused @throws
    }
}
```

[pepakriz]

This is the expected behavior.

But you can disable this "strict" mode by adding reportUnusedCheckedThrowsInSubtypes: false to your config file.

See #95

[Majkl578]

This doesn't make much sense in my opinion. @throws on interface method indicated the method MAY throw such exception, not that it will necessarily always do so. And not throwing such exception from the method at all is just a special and compatible case of such situation.
This is also how phpDoc defines it:

This tag is used to present in your documentation which error COULD occur and under which circumstances.

It also violates LSP principle - implementing methods are less restrictive than their ancestors.

In Java, for example, this is completely valid case: https://stackoverflow.com/a/15607166, https://coderanch.com/t/399874/java/Methods-throwing-Exception-Interface

---

Disabling reportUnusedCheckedThrowsInSubtypes works of course but I'd like to question the rule as whole. :)

[pepakriz]

Look: https://github.com/pepakriz/phpstan-exception-rules/blob/master/extension.neon#L4

The default behavior is exactly as you're saying. In the early version, there was just "strict" mode and then we reimplement it in LSP way, but we wanted to preserve compatibility. So at first, we introduced reportUnusedCheckedThrowsInSubtypes with default true (as minor version) and then false in next major version. Maybe it's time to deprecate it at all. Do you want to do that?

[VincentLanglet]

The solution I found was

interface Foo {
    /**
     * @throws SomeException
     */
    function bar(): void;
}

class SomeFoo implements Foo {
    /**
     * @throws void
     */
    public function bar(): void
    {
        // no throw here
    }
}
```

But I agree this was annoying.

The only interest in `throws void` is to avoid to report a missing try catch when calling `SomeFoo::bar`.

[Majkl578]

@VincentLanglet There are however some issues with @throws void:

• it's not valid according to phpDoc definition of @throws - void doesn't extend Throwable,
• it's hard to remove only some exceptions, e.g. would this be valid?

interface Foo {
    /**
     * @throws FirstException
     * @throws SecondException
     */
    function bar(): void;
}

class SomeFoo implements Foo {
    /**
     * @throws void
     * @throws SecondException
     */
    public function bar(): void
    {
        // only throws SecondException, not FirstException
    }
}

Also both Psalm and PHan report @throws void as invalid and that is IMO correct:

• https://psalm.dev/r/87f2f3634c
• https://phan.github.io/demo/?code=%3C%3Fphp%0A%0Ainterface+Foo+%7B%0A++++%2F**%0A+++++*+%40throws+SomeException%0A+++++*%2F%0A++++function+bar%28%29%3A+void%3B%0A%7D%0A%0Aclass+SomeFoo+implements+Foo+%7B%0A++++%2F**%0A+++++*+%40throws+void%0A+++++*%2F%0A++++public+function+bar%28%29%3A+void%0A++++%7B%0A++++++++%2F%2F+no+throws%0A++++%7D%0A%7D

[VincentLanglet]

I think the way to remove an exception is:

interface Foo {
    /**
     * @throws FirstException
     * @throws SecondException
     */
    function bar(): void;
}

class SomeFoo implements Foo {
    /**
     * @throws SecondException
     */
    public function bar(): void
    {
        // only throws SecondException, not FirstException
    }
}

@Majkl578 I created this issue phpstan/phpstan#3350, and closed it after the throws void response. Do you think I should re-open it ?

If Phpstan allows/recommend @throws void when Psalm/PHan don't, it will be hard to have all of them on the same project.
Does Psalm/PHan merge @throws tag too ?

Because if @throws tag are merged, without a way to say "This function does not throws exception", we have the following issue:

interface Foo {
    /**
     * @throws SomeException
     */
    function bar(): void;
}

class SomeFoo implements Foo {
    public function bar(): void
    {
        // no throw here
    }
}

class Bar {
    public function bar(): void
    {
        $someFoo = new SomeFoo();
        $someFoo->bar(); // -> cause unhandled SomeException
    }
}

[VincentLanglet]

Phpstan now support @phpstan-throws void.