Bring exceptions under control

Posted on by Anton Monakov

PhpStorm 2017.3 introduces several useful inspections and the corresponding quick-fixes for handling exceptions in your code.

Unhandled exception

Situations where executing your code will lead to a Fatal Error should be detected in advance and avoided. The new Unhandled exception inspection will help you with this by reporting exceptions that are not enclosed in a try-catch block, or that are not documented using the @throws tag. You can resolve the reported issues by using the provided Add @throws tag and the Surround with try-catch quick-fixes:


Redundant @throws tag

When refactoring your code, it’s always a good idea to make sure that your changes are reflected in the PHPDoc block.

In earlier releases, the Missing @throws tag(s) inspection checked that all the exceptions thrown by a function had been documented. The new Redundant @throws tag inspection serves the same purpose, though by doing exactly the opposite: it detects tags for which no exceptions are present in the function, and suggests removing them.

Using the corresponding Remove @throws tag and Update PHPDoc Comment quick-fixes, you will clean up your PHPDoc in a breeze:


Redundant catch clause

The new Redundant catch clause inspection will detect the situations in which the exception you are trying to catch is actually never thrown. Use the the corresponding Delete catch clause quick-fix to remove redundant catch blocks:


We hope that the new inspections will save you precious time and streamline your work with exceptions handling. If you need to customize the inspections’ severity level or define the scope they are applied to, navigate to Settings | Editor | Inspections and explore the PHP | Error handling and PHP | PHPDoc sections in the inspections list.

Your JetBrains PhpStorm Team
The Drive to Develop

Comments below can no longer be edited.

26 Responses to Bring exceptions under control

  1. Hy Cường says:

    December 1, 2017

    Hello, I want to turn off Unhandled exception but didn’t see

    Settings | Editor | Inspections | PHP | Probable bugs | Unhandled exception.

    Please check it

    • Hy Cường says:

      December 1, 2017

      Oh you can Turn it off via
      Settings | Editor | Inspections | PHP | Error handling | Unhandled exception.

      • Adam Cameron says:

        December 5, 2017

        This doesn’t seem to switch it off for me. Bloody annoying.

        • Maxim Kolmakov says:

          December 5, 2017

          Probably inspections warning are coming from Php Inspections (EA Extended) plugin in your case.

          • Adam Cameron says:

            December 5, 2017

            Nah, sorry: don’t have that installed. The only non-bundled plug-ins I seem to have are:

            Key Promoter X
            Markdown Navigator (and this one is disabled)

            It’s not the end of the world TBH. Currently how it greys-out the exception is distracting because it make me think something is amiss, when it isn’t. I’ll get used to it.

            Cheers for the suggestion though!

            • Artem Khvastunov says:

              March 6, 2018

              This is a different inspection. It’s located nearby in the settings and called Redundant catch clause. Also, you can always switch off any inspection just pressing Alt+Enter on a warning and using Disable inspection in the menu.

  2. Muhammad Furqan Siddiqui says:

    December 4, 2017

    Most useless feature

  3. Adam Cameron says:

    December 5, 2017

    This is a bit of a strange thing to add, IMO. PHP doesn’t have the concept of checked exceptions, so I dunno if it’s actually appropriate to pretend that it does.

    • [M] says:

      December 6, 2017

      Regardless what concept PHP has or not, I think it’s great that my IDE tells me that I have unhandled exceptions in my code.

      • Adam Cameron says:

        December 6, 2017

        But that’s not what it does. It tells you that you don’t have a *comment* in your code. It doesn’t say anything about whether I’m actually throwing that exception or not. Cos the code *is* throwing that exception, but it’s not correctly identifying that, because it solely seems to rely on the comment rather than the code.

        And in fact it’s not even what it does anyhow. The catch block *is* handling the exception. It erroneously reports that it _doesn’t need to handle it_ cos it’s not being thrown in the first place.

        Now if it actually flagged up an exception situation and said “yer not handling this” – ie: not catching it, or actively saying “I’m not catching this on purpose” – then it might have some merit. It doesn’t do that though, does it?

        Still: I wouldn’t care if I could switch the thing off.

        • [M] says:

          December 6, 2017

          I think there is some misunderstanding here, this this feature does exactly what you described in the last part of your comment.

          Let’s say you have a method, and inside you throw an exception, or you call a method that throws one.

          With this feature you will know immediately that there is a potential unhandled exception that needs to be taken care of. You can do that either by catching it yourself, or documenting that the user of your method should be the one who handles it.

          > The catch block *is* handling the exception. It erroneously reports that it _doesn’t need to handle it_ cos it’s not being thrown in the first place.

          What? My english sucks, it’s just a secondary language, but I don’t really understand what you are trying to say.

          • Adam Cameron says:

            December 6, 2017

            Don’t worry about your English: it’s fine.

            But here’s some example code:

            So to be clear… it’s not telling me I have an unhandled exception. It’s telling me I am handling an exception I don’t need to.

            • [M] says:

              December 6, 2017

              Now I understand your problem 🙂

              But actually that’s not what’s happening. At least not for me. I had to fix up your code, but it’s is basically the same:


              As you can see PHPStorm realizes that there is an unhandled exception thrown in someMethod, and it is not complaining about that in the body of f(). It is only complaining about that the thrown exception is not handled or documented.

              Anyway. I believe in good documentation. It helps yourself, it helps the developer(s) who use your code and it helps the IDE that analyzes the code so that it may help you even further.

              In this case the phpdoc tag of someMethod should have stated that it may throw SomeExcepiton so even if your IDE doesn’t recursively analyze method calls, it will know what to expect from that method, and warn you about potential issues

              • Adam Cameron says:

                December 6, 2017

                That’s not what I’m seeing. For me it’s greying-out SomeException where I indicated in the gist, and if I hover it tells me the try block is not throwing that exception. Now in my case it’s not that _exact_ code, but it’s roughly analogous. And the code is definitely (conditionally) throwing that exception.

                I have an unpopular position on docblocks in that they are mostly a bad thing. Like almost all comments they are prone to lie-telling, and are best avoided. Even if one does use ’em, it should be literally for documentation only; it should not be the basis for analysis like in an inspection. Only the actual code should be used, because it’s *the actual code* that defines the real behaviour. The comments do not.

                Still: all IMO. I do not expect you to agree, nor am I saying my opinion is somehow right and yours is not, or is less so or anything like that.

                And hey – thanks for spending the time discussing this. Much appreciated and it’s all interesting stuff.

              • Artem Khvastunov says:

                March 6, 2018

                I’ve just commented on your gist. If you transform the code to the form when types are unambiguously defined, PhpStorm properly handles thrown and caught exceptions. The point is, that you don’t need to places docs anywhere while all the information which is necessary for a static analysis is available.

                Update. Oh, the [M]’s comment was partially hidden for me. So, I’ve basically repeated what was already said.

  4. Dmitry Shashkin says:

    December 6, 2017

    Every db query can thow an exception,which means that with this feature enabled I have to add a @throws tag to every method that at some point down the call chain queries the database. As this is the case with most of my methods I would end up having a “throws” tag above every method in my project. That seems a bit redundant. At the same time I’m still reluctant to turn off this feature completely, as it does have some merit in other situations. So what is the suggested way to handle such situation?

    • Dmitry Tronin says:

      December 7, 2017

      It’s better to describe your use case in details at for us to review. Here’s an example:

      • John Aitchison says:

        December 29, 2017

        Given that there are many open issues in youtrack with hundreds of votes and many years old, I’d have to say pointing out something like this in the blog where it’s visible to the world — which has caused our IDE to become chock full of warnings we aren’t interested in — may in fact be the better way to bring attention to the issue.

        For example, this issue described by Dmitry Shashkin was marked as a duplicate of this more-than-3-year-old issue

        • Dmitry Tronin says:

          January 2, 2018

          That’s a hot topic right now (exceptions handling), so every concern or usability issue reported at our bugtracker is being carefully investigated. Even though that particular report was marked as duplicate – that doesn’t mean that it isn’t taken into consideration.

    • Adam Cameron says:

      December 7, 2017

      Agreed. This is part of the reason why checked exceptions are falling out of favour in Java, aren’t they? They just add even more boilerplate to an already-boilerplate-heavy language. Features like this in PHPStorm are encouraging adding new boilerplate to a language that was pleasingly free of it to start with (as any loosely- & dynamically-typed language ought to be).

    • Lionel says:

      December 11, 2017

      @dmitryshashkin:disqus An issue was created, please vote for it here to speed things up:

  5. Matúš Čák says:

    December 10, 2017

    Is this feature checking all types of exceptions or some of them are excluded? In my code, it seems that it ignores cases where “built-in” types are thrown, for example InvalidArgumentException.

    What are the exact rules what is checked and what is not?

    • Dmitry Tronin says:

      December 11, 2017

      The inspection reports exceptions which are neither enclosed in a try-catch block nor documented using the ‘@throws’ tag.

    • Artem Khvastunov says:

      March 6, 2018

      LogicException and RuntimeException derivatives are ignored by default, but it can be configured in settings.

  6. Maxime Wegesin says:

    March 12, 2018

    Really like this feature and find it generally useful. However I agree that sometimes it just does not make sense to use it. You can locally disable it via


Subscribe for updates