guzzle: PhpStorm warns about unhandled GuzzleException

Q	A
Bug?	no
New Feature?	no
Version	6.3.3

Not a bug, just inconvenience in development. The PhpStorm IDE has built-in code analysis and it warns on my code which uses (new GuzzleHttp())->send() method without catching GuzzleException exeption. But I’m catching ClientException and RequestException instead and I think this should be enough. Here’s my code:

    /**
     * @param Request $request
     * @return Response
     */
    protected function executeRequest(Request $request): Response
    {
        $this->lastRequest = $request;
        try {
            $this->lastResponse = (new GuzzleHttp())->send($request, $this->getRequestOptions());
        } catch (ClientException $e) {
            $this->lastResponse = $e->getResponse();
            throw new FatalException($this->getExceptionMessage($e));
        } catch (RequestException $e) {
            $this->lastResponse = $e->getResponse();
            throw new Exception($this->getExceptionMessage($e));
        }
        return $this->lastResponse;
    }

PhpStorm wants me to add yet another catch section with GuzzleException (which is not exception actually, just interface) or to add:

     * @throws \GuzzleHttp\Exception\GuzzleException

in PhpDoc of my method.

The problem is going from ClientInterface where PhpDoc describes that it @throws GuzzleException:

    /**
     * Send an HTTP request.
     *
     * @param RequestInterface $request Request to send
     * @param array            $options Request options to apply to the given
     *                                  request and to the transfer.
     *
     * @return ResponseInterface
     * @throws GuzzleException
     */
    public function send(RequestInterface $request, array $options = []);

and concrete implementation Client doesn’t have PhpDoc at all:

    public function send(RequestInterface $request, array $options = [])
    {
        $options[RequestOptions::SYNCHRONOUS] = true;
        return $this->sendAsync($request, $options)->wait();
    }

This is why PhpStorm takes throwing exceptions from interface. Please add PhpDoc to Client::send() method. This will override @throws tag in the interface and fix the problem.

I think that declaring in PhpDoc @throws tag the class which is not descendant of \Exception class is anti-pattern and bad practice. It forces developers to catch this exception which is not exception. Make GuzzleException abstract class extending from \RuntimeException and inherit from it all other classes if needed or not use it in @throws tags.

Actually you don’t need to declare @throws tags since all your exceptions are inherited from \RuntimeException. This kind of exceptions that can happen almost anywhere and you can but don’t have to catch it everywhere. This is why you don’t need to add it in PhpDoc. This logic is taken from Java. In the Java only RuntimeException can be not catched. Otherwise the code will not compile.