Exceptions in PHP

Best practices for using exceptions in PHP.
How to design exception hierarchies.
Difference between runtime and usage (logic) error.

1. Jan Tvrdík

2. try {
...
if (!$ok) {
throw new FooException();
}

} catch (FooException $e) {
...
}

3. try {
...
if (!$ok) {
throw new FooException();
}

} catch (FooException $e) {
...
} catch (BarException $e) {
...
}

4. try {
...
if (!$ok) {
throw new FooException();
}

} catch (FooException $e) {
...
} finally {
...
}

5. try
catch finally
Was there
an exception thrown?
Is there a corresponding
catch block?
Yes
Yes
No
No

6. try {
$this->db->lock('users');
$this->db->query(...);
$this->db->unlock();

// intentionally catch all exceptions
} catch (Exception $e) {
$this->db->unlock();
throw $e;
}

7. try {
$this->db->lock('users');
$this->db->query(...);
$this->db->unlock();

// intentionally catch all exceptions
} catch (Exception $e) {
$this->db->unlock();
throw $e;
}

8. try {
$this->db->lock('users');
$this->db->query(...);

} finally {
$this->db->unlock();
}

9. try {
return 1;

} finally {
return 2;
}

10. constructor parameters
string $message = ""
int $code = 0
Exception $previous = NULL
methods
string getMessage()
Exception getPrevious()
mixed getCode()
string getFile()
int getLine()
array getTrace()

11. usage error
runtime error
System failure

12. can be avoided
should directly lead to a fix
message is more important than type
very important in libraries
should not be catched
examples:
wrong argument type / value
calling method in incorrect order
creating an instance of static class
calling not implemented method

13. can NOT be avoided
type is more important than message
should be catched
often related to thread safety
examples:
file / directory / database entry not found
duplicate entry in database

14. Exception
ErrorException

LogicException (for usage errors)
InvalidArgumentException
RuntimeException (for runtime errors)

16. Exception
LogicException
App\LogicException
App\InvalidArgumentException
App\NotImplementedException
App\StaticClassException
RuntimeException
…

17. Exception
LogicException
…
RuntimeException
App\RuntimeException
App\IOException
App\FileNotFoundException
App\DirectoryNotFoundException
App\EntryNotFoundException
App\DuplicateEntryException

18. throw only exceptions from your namespace
usage error
write nice ex. message for human developer
runtime error
use very specific type
(often requires creating a new one)
message is often useless
phpDoc
Always specify all runtime exceptions
@throw annotation is part of API

19. never display ex. message to the user
catch as specific types as possible
read and respect @throw annotations
use $previous when rethrowing ex.

20. Twitter + GitHub
@JanTvrdik

nette.merxes.cz