7 Tips to Write Exceptions Everyone Will Love

This post was updated at November 2020 with fresh know-how.
What is new?

Updated content with simpler examples. Switched YAML to PHP configuration, as current standard.


InvalidArgumentException, FileNotFoundException, InternalException.

Have you ever had that feeling, that you've seen that exception before and you know what it means and how to solve? What if that would be clear even for those who see it for the first time? It would save yours and their time.

Exceptions are not just error state. Exceptions are the new documentation.

I wrote a 50-page thesis about polyphasic sleep. My opponent told me, that there is a missing part about uncontrolled intervening values. The part in pages 34-36 he probably skipped. Today we have too much going on we have to scan. Anything longer than 140 chars is exhausting. Moreover for us programmers, who dance among tsunami of information coming every hour as they code and investigate code of others.

Do you Find this "Circle of Code" Familiar?

  1. you open the application
  2. you code and code, life is great!
  3. suddenly, it's broken by InvalidStateException exception (if we're lucky)
  4. you open exception in IDE to find out more... nothing
  5. you open the documentation to find out more... nothing
  6. you Google and StackOverflow to find out more... nothing
  7. you close the application frustrated, have a ☕ or social joint to restore your will to overcome shit code

What if you could stay between 1, 2 and 3 much more often?


When people used EasyCodingStandard for their first time, they experienced many WTFs. After 30 minutes they gave up saying "coding standards are hard". When I asked them to show me how they used it, it took me 3 minutes to solve. Why? Because I made it? Well maybe. But also because exceptions were so lousy, that nobody knew how to solve them and that's wrong. Shame on me.

1. Make Exception Names for Humans

Not machines but people read exceptions. Well, machines read it to but they just log it - humans have to make code work again.

InvalidStateException

WTF? Could you be more clear?

ConfigurationFileNotFoundException

A-ha, I create ecs.php and it works!

+10 % happier programmer

Do you need help with this? There is Sniff that makes sure no exception is generic.

2. Use " around" Statements

Filter class VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd was not found
<?php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set('filters', [
        ' VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd'
    ]);
};

The class exists and it is autoloaded:

require_once __DIR__ . '/vendor/autolaod.php'

var_dump(class_exists(
    VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd::class
));
// "true"

So what is wrong?


5 minutes later...

 <?php

 declare(strict_types=1);

 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

 return function (ContainerConfigurator $containerConfigurator): void {
     $parameters = $containerConfigurator->parameters();
     $parameters->set('filters', [
-        ' VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd'
+        'VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd'
     ]);
 };

Ah, there was a space, a single small space!

You probably noticed it, because there are 3 lines of code and they get all your attention. In reality, there are 80 lines of code, 5 files opened in your IDE/brain and your colleague is asking you for wise advice, so your chances to spot this are much lower.

How to prevent this from happening ever again to anyone in the world?

Filter class VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd was not found
*Filter class " VeryLongNamespace\InNestedNamespace\WithMissingClassInTheEnd" was not found*

Use quotes around every argument:

throw new FilterClassNotFoundException(sprintf(
    'Filter class "%s" was not found',
    $filterClass
));

+20 % happier programmer

3. What Exactly is Wrong?

main parameter is invalid
throw new InvalidParameterException(sprintf(
    '%s parameter is invalid.',
    $parameterName
));

What parameter?

"main" parameter is invalid
 throw new InvalidParameterException(sprintf(
-    '%s parameter is invalid.',
+    '"%s" parameter is invalid.',
     $parameterName
));

Aha! Where do I find it? In the "parameters" section?

Parameter in "parameters > page_name > main" is invalid
throw new InvalidParameterException(sprintf(
    'Parameter in "parameters > page_name > %s" is invalid.',
    $parameterName
));

Aha, now I know where to find it, thanks!

<?php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set('page_name', [
        'main' => []
    ]);
};

+20 % happier programmer

4. What is The Wrong Value?

Parameter in "parameters > page_name > main" is invalid

We already know where it is, but what value it actually has?

Parameter value "false" in "parameters > page_name > main" is invalid

I see, so "main" parameter can't have false value. What it can have then?

Parameter value "false" in "parameters > page_name > main" is invalid. It must be a string
if (is_array($value)) {
    $value = 'array';
} elseif (is_bool($value)) {
    $value = ($value === true) ? 'true' : 'false';
}

throw new InvalidParameterException(sprintf(
    'Parameter value "%s" in "parameters > page_name > %s" is invalid. It must be a string.',
    $value,
    $parameterName
));

+15 % happier programmer

Tip: You can use Tracy to delegate the value dumping.

5. What File Exactly is Broken?

Invalid file

In EasyCodingStandard, PHP_CodeSniffer, PHP CS Fixer, Rector or PHPStan there is always work with files. Is there some error with the file? Show it!

File /var/www/tomasvotruba.com/packages/src/TweetPublisher.php not found

Oh, sorry:

File "/var/www/tomasvotruba.com/packages/src/TweetPublisher.php" not found

Absolute paths can be really long in Docker, CI or in the non-basic install. We don't need irrelevant information - every character counts!

How can we make it a bit more familiar to the user? Show the relative path:

File "packages/src/TweetPublisher.php" not found

How to do this nice and lazy in PHP?

// "$filePath" can be absolute or relative; we don't care, it only must exists
$fileInfo = new SplFileInfo($filePath);

// remove absolute path start to cwd (current working directory)
$relativePath = substr($fileInfo->getRealPath(), strlen(getcwd()) + 1);

throw new FileProcessingException(sprintf(
    'File "%s" not found',
    $relativePath
));

+20 % happier programmer

6. What Options do I have?

vendor/bin/finder show laravel
"laravel" was not found

Don't make the programmer think!

Level "laravel" was not found. Pick one of: "symfony", "nette", "zend"

That's better!

If there is the limited or reasonable amount of options, don't be shy. Show them!

$allOptions = $this->findAllLevelsInDirectory($configDirectory);

throw new OptionNotFoundException(sprintf(
    'Option "%s" was not found. Pick one of: "%s"',
    $optionName,
    implode('", "', $allOptions)
));

+40 % happier programmer

7. Link what You can't Fit 140 Chars

Sometimes you might find yourself writing a poem instead of an exception:

throw new ConfigurationFileNotFound(
    'Class not found. Configure autoload, you can use either `parameters > autoload_files`' .
    'or `parameters > autoload_directories`. Be careful to use paths relative to the file you are using.'
);

Who would read that? Except for the author of course.

To make it shorted and readable, we end up with a lousy statement like:

throw new ConfigurationFileNotFound('Class not found. Configure autoload first.');

10 Tweets = 1 post, so just link it!

throw new ConfigurationFileNotFound(
    'Class not found. Configure autoload: https://github.com/rectorphp/rector/blob/master/README.md'
);

A bit more perfect? Use headline anchor:

throw new ConfigurationFileNotFound(
    'Class not found. Configure autoload: https://github.com/rectorphp/rector/blob/master/README.md#extra-autoloading'
);

Here is one pitfall - end of lines and line breaks in CLI. You might end up with this error message:

https://github.com/rectorphp/rector/blob/
master/README.md#extra-autoloading

Where only https://github.com/rectorphp/rector/blob/ is a link. Invalid link.

How to save this?

throw new ConfigurationFileNotFound(
    'Class not found. Configure autoload:' .
    PHP_EOL .
    'https://github.com/rectorphp/rector/blob/master/README.md#extra-autoloading'
);

Kaboom!

+30 % happier programmer


And in these 7 steps, you just made any programmer using your code 125 % happier!

What are your the most favorite exceptions?


Happy throwing!




Do you learn from my contents or use open-souce packages like Rector every day?
Consider supporting it on GitHub Sponsors. I'd really appreciate it!