DPC 2018 - Journey Through "Unhappy Path"

Developers naturally gravitate towards the "happy path" - default scenario in application execution in which everything works as expected, consequently neglecting exceptional behavior aspect of a software development.

This talk provides a comprehensive insight into widely adopted practices and patterns for dealing with exceptional conditions. Emphasis is on exceptions and applicable techniques that improve quality of the overall architecture, such as:

- structuring and organizing custom exception classes
- formatting exception messages using named constructors technique
- component-level exception
- exception wrapping

To make the story complete, second part of the talk focuses on a PHP-based solution for establishing a robust and extensible error handling system.

Transcript

1. JOURNEY THROUGH JOURNEY THROUGH "UNHAPPY PATH" "UNHAPPY PATH" DEALING WITH EXCEPTIONAL CONDITIONS DEALING WITH EXCEPTIONAL CONDITIONS Nikola Poša Dutch PHP Conference 2018
2. NIKOLA POŠA NIKOLA POŠA Software Architect and Open-Source Contributor Head of Data Integration @ Arbor Education Partners PHPSerbia Conference co-organizer  @nikolaposa  nikolaposa  blog.nikolaposa.in.rs
3. (UN)HAPPY PATH (UN)HAPPY PATH a.k.a. Normal Flow "Happy path is a default scenario featuring no exceptional or error conditions, and comprises nothing if everything goes as expected." Wikipedia
4. final class DbArticleRepository implements ArticleRepositoryInter { private $dbConnection; public function __construct(Connection $dbConnection) { $this->dbConnection = $dbConnection; } public function get(string $id) { $articleRecord = $this->dbConnection->fetchAssoc( "SELECT * FROM articles WHERE id = ?", [$id] ); return new Article($articleRecord); } }
5. What can possibly go wrong? final class DbArticleRepository implements ArticleRepositoryInter { private $dbConnection; public function __construct(Connection $dbConnection) { $this->dbConnection = $dbConnection; } public function get(string $id) { $articleRecord = $this->dbConnection->fetchAssoc( "SELECT * FROM articles WHERE id = ?", [$id] ); return new Article($articleRecord); } }
6. EXCEPTIONAL BEHAVIOUR EXCEPTIONAL BEHAVIOUR final class DbArticleRepository implements ArticleRepositoryInter { public function get(string $id) { $articleRecord = $this->dbConnection->fetchAssoc( "SELECT * FROM articles WHERE id = ?", [$id] ); if (false === $articleRecord) { //??? } return new Article($articleRecord); } }
7. final class DbArticleRepository implements ArticleRepositoryInter { public function get(string $id) { $articleRecord = $this->dbConnection->fetchAssoc( "SELECT * FROM articles WHERE id = ?", [$id] ); if (false === $articleRecord) { return null; } return new Article($articleRecord); } }
9. "When we return null, we are essentially creating work for ourselves and foisting problems upon our callers." Robert C. Martin, "Clean Code"
10. "All it takes is one missing null check to send an application spinning out of control." Robert C. Martin, "Clean Code"
11. "All it takes is one missing null check to send an application spinning out of control." Robert C. Martin, "Clean Code" Fatal error: Call to a member function getId() on null
12. "If you are tempted to return null from a method, consider throwing an exception or returning a Special Case object instead." Robert C. Martin, "Clean Code"
13. public function get(string $id) : Article { $articleRecord = $this->dbConnection->fetchAssoc("SELECT * FRO if (false === $articleRecord) { throw new ArticleNotFoundException(); } return new Article($articleRecord); } interface ArticleRepositoryInterface { /** * @param string $id * @return Article * @throws ArticleNotFoundException */ public function get(string $id) : Article; }
14. SPECIAL CASE SPECIAL CASE "A subclass that provides special behavior for particular cases." Martin Fowler, "Patterns of Enterprise Application Architecture"
15. class DeadArticle extends Article { public function getTitle() : string { return 'Nothing here'; } public function getContent() : string { return 'Go back to <a href="/">Home Page</a>'; } } final class DbArticleRepository implements ArticleRepositoryInter { public function get(string $id) : Article { $articleRecord = $this->dbConnection->fetchAssoc("SELECT if (false === $articleRecord) { return new DeadArticle(); } return new Article($articleRecord); } }
16. Get rid of checks for a null value echo $article ? $article->getTitle() : 'Non-existing article';
17. Get rid of checks for a null value echo $article->getTitle();
18. "Returning null from methods is bad, but passing null into methods is worse." Robert C. Martin, "Clean Code"
19. class Order { public function __construct( Product $product, Customer $customer, DiscountInterface $discount = null ) { //... } } final class PremiumDiscount implements DiscountInterface { public function apply(float $productPrice) : float { return $productPrice * 0.5; } }
20. class Order { //... public function getTotal() : float { $price = $this->product->getPrice(); if (null !== $this->discount) { $price = $this->discount->apply($price); } return $price; } }
21. class Order { public function __construct( Product $product, Customer $customer, DiscountInterface $discount ) { //... } public function getTotal() : float { $price = $this->product->getPrice(); $price = $this->discount->apply($price); return $price; } }
22. final class NoDiscount implements DiscountInterface { public function apply(float $productPrice) : float { return $productPrice; } } $order = new Order($product, $customer, new NoDiscount());
24. EXCEPTION VS SPECIAL CASE EXCEPTION VS SPECIAL CASE
25. Input validation class User { public static function fromInput(array $input) : User { if (!filter_var($input['email'], FILTER_VALIDATE_EMAIL)) throw new InvalidUserInputException(); } //... } }
26. Enforce business rule class ArticleService { public function get(string $articleId) : Article { $articles = $this->articleRepo->findByCriteria([ 'id' => $articleId, ]); if ($articles->isEmpty()) { throw new ArticleNotFoundException(); } return $articles->first(); } }
27. USING EXCEPTIONS USING EXCEPTIONS Should be simple as: throw new \Exception('Article with the ID: ' . $id . ' does not ex
29. CUSTOM EXCEPTION TYPES CUSTOM EXCEPTION TYPES bring semantics to your code emphasise exception type instead of exception message allow caller to act differently based on Exception type
30. STRUCTURING EXCEPTIONS STRUCTURING EXCEPTIONS src/ Article/ Exception/ Article.php ArticleCollection.php ArticleRepositoryInterface.php Author/ Exception/ Author.php AuthorRepositoryInterface.php
31. CREATING EXCEPTION CLASSES CREATING EXCEPTION CLASSES class ArticleNotFoundException extends \RuntimeException { } src/ Article/ Exception/ ArticleNotFoundException.php InvalidArticleException.php
32. COHESIVE EXCEPTION CLASSES COHESIVE EXCEPTION CLASSES
33. COHESIVE EXCEPTION CLASSES COHESIVE EXCEPTION CLASSES class ArticleException extends Exception { }
34. COHESIVE EXCEPTION CLASSES COHESIVE EXCEPTION CLASSES class ArticleNotFoundException extends \RuntimeException { } class InvalidArticleException extends \DomainException { }
35. COMPONENT LEVEL EXCEPTION TYPE COMPONENT LEVEL EXCEPTION TYPE Exception type that can be caught for any exception that comes from a certain component.
36. COMPONENT LEVEL EXCEPTION TYPE COMPONENT LEVEL EXCEPTION TYPE Exception type that can be caught for any exception that comes from a certain component. namespace App\Article\Exception; interface ExceptionInterface { } class InvalidArticleException extends \DomainException implements ExceptionInterface { } class ArticleNotFoundException extends \RuntimeException implement ExceptionInterface { }
37. use GuzzleHttp\Exception\ClientException; use GuzzleHttp\Exception\ServerException; use GuzzleHttp\Exception\GuzzleException; //marker interface try { //code that can emit exceptions } catch (ClientException $ex) { //... } catch (ServerException $ex) { //... } catch (GuzzleException $ex) { //... }
38. FORMATTING EXCEPTION MESSAGES FORMATTING EXCEPTION MESSAGES Encapsulate noisy message formatting logic into the Exception classes themselves.
39. throw new ArticleNotFoundException(sprintf( 'Article with the ID: %s does not exist', $id ));
40. throw new ArticleNotFoundException(sprintf( 'Article with the ID: %s does not exist', $id )); throw new InsufficientPermissionsException(sprintf( 'You do not have permission to %s %s with the id: %s', $privilege, get_class($entity), $entity->getId() ));
41. class ArticleNotFoundException extends \RuntimeException implement { public static function forId(string $id) { return new self(sprintf( 'Article with the ID: %s does not exist', $id )); } }
42. class ArticleNotFoundException extends \RuntimeException implement { public static function forId(string $id) { return new self(sprintf( 'Article with the ID: %s does not exist', $id )); } } throw ArticleNotFoundException::forId($id);
43. PROVIDE CONTEXT PROVIDE CONTEXT Save/expose the context of the exceptional condition that has occurred.
44. PROVIDE CONTEXT PROVIDE CONTEXT Save/expose the context of the exceptional condition that has occurred. final class ArticleNotFoundException extends \RuntimeException imp { private $articleId; public static function forId(string $articleId) { $ex = new self(sprintf('Article with the ID: %s does not $ex->articleId = $articleId; return $ex; } public function getArticleId() : string { return $this->articleId; } }
45. EXCEPTION WRAPPING EXCEPTION WRAPPING Wrap exceptions thrown from a lower layer into appropriate exception which is meaningful for the context of the higher layer operation.
46. EXCEPTION WRAPPING EXCEPTION WRAPPING Wrap exceptions thrown from a lower layer into appropriate exception which is meaningful for the context of the higher layer operation. try { $this->httpClient->request('GET', '/products'); } catch (ConnectException $ex) { throw ApiNotAvailableException::forError($ex); } class ApiNotAvailableException extends \RuntimeException implement { public static function forError(ConnectException $error) { return new self('API is not available', 0, $error); //pre } }
47. TO SUM UP TO SUM UP create custom, cohesive Exception types introduce component-level exception type using Marker Interface encapsulate message formatting logic into Exception classes via Named Constructors save/provide context of the exceptional situation apply exception wrapping technique
48. ERROR HANDLING ERROR HANDLING
49. CHALLENGES CHALLENGES versatility user experience security monitoring / reporting
50. INLINE ERROR HANDLING INLINE ERROR HANDLING class ArticleController extends BaseController { public function viewAction(RequestInterface $request) { try { $article = $this->articleService->get($request->get(' $this->view->article = $article; } catch (ArticleNotFoundException $ex) { $this->view->error = 'Article not found'; } catch (\Exception $ex) { $this->view->error = $ex->getMessage(); } } }
51. ERROR CONTROLLER ERROR CONTROLLER class ErrorController { public function errorAction() { $error = $this->getRequest()->getParam('error_handler'); switch ($error->type) { //... } } }
52. ERROR MIDDLEWARE ERROR MIDDLEWARE class ErrorHandler implements MiddlewareInterface { public function __invoke(RequestInterface $request, ResponseI { try { $response = $next($request, $response); } catch (\Throwable $e) { $response = $this->handleError($e, $request); } return $response; } }
53. CHALLENGES CHALLENGES versatility user experience security monitoring / reporting
54. CENTRAL ERROR HANDLER CENTRAL ERROR HANDLER Wraps the entire system to handle any uncaught exceptions from a single place.
55. CUSTOM SOLUTION CUSTOM SOLUTION set_error_handler(function ($errno, $errstr, $errfile, $errline) if (! (error_reporting() & $errno)) { return; } throw new ErrorException($errstr, 0, $errno, $errfile, $errli }); set_exception_handler(function ($exception) { //log exception //display exception info });
56. EXISTING SOLUTIONS EXISTING SOLUTIONS
57. EXISTING SOLUTIONS EXISTING SOLUTIONS - stack-based error handling, pretty error page, handlers for different response formats (JSON, XML) Whoops
58. EXISTING SOLUTIONS EXISTING SOLUTIONS - stack-based error handling, pretty error page, handlers for different response formats (JSON, XML) - different formatting strategies (HTML, JSON, CLI), logging handler, non-blocking errors Whoops BooBoo
59. Using Whoops final class ErrorHandlerFactory { public function __invoke(ContainerInterface $container) { $whoops = new \Whoops\Run(); if (\Whoops\Util\Misc::isAjaxRequest()) { $whoops->pushHandler(new JsonResponseHandler()); } elseif (\Whoops\Util\Misc::isCommandLine()) { $whoops->pushHandler(new CommandLineHandler()); } else { $whoops->pushHandler(new PrettyPageHandler()); } $whoops->pushHandler(new SetHttpStatusCodeHandler()); $whoops->pushHandler(new LogHandler($container->get('Defau return $whoops; } }
60. src/bootstrap.php public/index.php bin/app //... initialize DI container $container->get(\Whoops\Run::class)->register(); return $container; $container = require __DIR__ . '/../src/bootstrap.php'; $container->get('App\Web')->run(); $container = require __DIR__ . '/../src/bootstrap.php'; $container->get('App\Console')->run();
61. Logging errors selectively final class LogHandler extends Handler { public function handle() { $error = $this->getException(); if ($error instanceof DontLogInterface) { return self::DONE; } $this->logger->error($error->getMessage(), [ 'exception' => $error, ]); return self::DONE; } }
62. class ArticleNotFoundException extends \RuntimeException implement ExceptionInterface, DontLogInterface { //... }
63. Setting HTTP status code final class SetHttpStatusCodeHandler extends Handler { public function handle() { $error = $this->getException(); $httpStatusCode = ($error instanceof ProvidesHttpStatusCo ? $error->getHttpStatusCode() : 500; $this->getRun()->sendHttpCode($httpStatusCode); return self::DONE; } }
64. interface ProvidesHttpStatusCodeInterface { public function getHttpStatusCode() : int; } class ArticleNotFoundException extends \RuntimeException implement ExceptionInterface, DontLogInterface, ProvidesHttpStatusCodeInterface { //... public function getHttpStatusCode() : int { return 404; } }
65. "The OCP (Open-Closed Principle) is one of the driving forces behind the architecture of systems. The goal is to make the system easy to extend without incurring a high impact of change." Robert C. Martin, "Clean Architecture"
66. TEST EXCEPTIONAL BEHAVIOUR TEST EXCEPTIONAL BEHAVIOUR a.k.a. Negative Testing
67. TESTING EXCEPTIONS WITH PHPUNIT TESTING EXCEPTIONS WITH PHPUNIT class ArticleTest extends TestCase { /** * @test */ public function it_cannot_be_commented_if_comments_are_closed { $article = new Article(); $article->closedForComments(); $this->expectException(CommentsAreClosedException::class) $article->comment(Comment::fromArray([ 'name' => 'John', 'email' => 'john@example.com', 'comment' => 'test comment', ])); } }
68. ARRANGE-ACT-ASSERT ARRANGE-ACT-ASSERT 1. initialize SUT/prepare inputs 2. perform action 3. verify outcomes
69. class ArticleTest extends TestCase { /** * @test */ public function it_can_be_commented() { $article = new Article(); $article->comment(Comment::fromArray([ 'name' => 'John', 'email' => 'john@example.com', 'comment' => 'test comment', ])); $this->assertCount(1, $article->getComments()); } }
70. /** * @test */ public function it_cannot_be_commented_if_comments_are_closed() { $article = Article::fromArray(['id' => '5']); $article->closedForComments(); try { $post->comment(Comment::fromArray(['comment' => 'test comm $this->fail('Exception should have been raised'); } catch (CommentsAreClosedException $ex) { $this->assertSame('Article #5 is closed for comments', $ex } }
71. FEEDBACK FEEDBACK Please rate this talk at: joind.in/talk/889aa
72. THANK YOU! THANK YOU! Nikola Poša  posa.nikola@gmail.com  @nikolaposa