Features Releases

Docblock Improvements for @throws in PhpStorm 2016.2

Writing docblocks is slow and tedious, so any help that your IDE can give you is always useful. PhpStorm 2016.2 has improved the way that the `@throws` annotation is detected and generated to save you having to create these annotations yourself.

PhpStorm 2016.2 brings two distinct improvements to its `@throws` annotation support. Firstly, we’ve unified the settings for annotation inspection and generation, which means that you won’t ever have a discrepancy between the warnings you’re getting, and the code that’s generated. You can find these settings in the Code Style settings pane, under PHP, PHPDoc, @throws Tag Analysis.

throws-settings

You’ll notice that we also have a brand new setting here that allows you to tell PhpStorm how many method calls deep you’d like to go to find exceptions to add to the throws block. This new feature means that when you have nested method calls each throwing different exceptions, then all the exceptions will be added to the `@throws` docblock.

<?php

class Throws
{

    /**
     * @param bool $throw
     * @throws \BadMethodCallException
     * @throws \InvalidArgumentException
     */
    public function doSomething($throw = true)
    {
        if ($throw) {
            throw new BadMethodCallException();
        }

        $this->throwException();
    }

    /**
     * @param string $message
     * @throws \InvalidArgumentException
     */
    private function throwException($message = 'Invalid Argument!!!')
    {
        throw new \InvalidArgumentException($message);
    }

}

Notice how the public method now gets the exception thrown in the private method added to its `@throws` list.

It’s worth noting here that setting the call tree analysis depth to more than 1, while possible, is not recommended. Any depth over one will work, but has the potential to slow down the IDE considerably, which can be a pain.

As usual, we’d love to hear what you think of these new improvements, so give it a try and let me know.

 – Gary and the PhpStorm Team

image description