From e3b0182b1d881e7c3e0b8c21d162b763bbdc8cd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kucha=C5=99?= <honza.kuchar@grifart.cz>
Date: Tue, 6 Nov 2018 20:14:30 +0100
Subject: [PATCH] Update README.md
---
README.md | 43 ++++++++++++++++++++++++++++++++++++++-----
1 file changed, 38 insertions(+), 5 deletions(-)
diff --git a/README.md b/README.md
index 604262b..35270d9 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,11 @@
repositories: [Grifart GitLab](https://gitlab.grifart.cz/grifart/suppressed-exceptions), [GitHub](https://github.com/grifart/suppressed-exceptions)
-Suppressed exceptions are useful for aggregating more exceptions with unreliable resources.
+Suppressed exceptions are useful for aggregating more exceptions from unreliable resources.
-You want to communicate that process failed, with following list of sibling exceptions that led to this error.
+Useful when you want to communicate that process failed, with a list of sibling exceptions that led to an error.
+
+## Example usage
```php
$remoteSources = []; // classes representing unreliable remote sources
@@ -12,17 +14,48 @@ $remoteSources = []; // classes representing unreliable remote sources
$exceptions = [];
foreach ($remoteSoures as $remoteSource) {
try {
- $remoteSource->fetch(); // unrealiable
+ $remoteSource->fetch(); // unsafe operation
} catch (FetchingFailed $e) {
$exceptions[] = $e;
continue;
}
}
-if (count($exceptions) > 0) {
+if (count($exceptions) > 0) {
$e = new ProcessingFailed();
$e->addSuppressed(...$exceptions);
throw $e;
}
+```
+
+You can also override exception constructor to provide better API
+
+```php
+final class EventPropagationFailedException extends \RuntimeException implements \Grifart\SuppressedExceptions\WithSuppressedExceptions
+{
+ use \Grifart\SuppressedExceptions\SuppressedExceptions;
+
+ public function __construct(\Throwable ...$suppressed)
+ {
+ parent::__construct('Saving succeeded, but some listeners failed to complete their job. Please check suppressed exceptions for more information.');
+ $this->addSuppressed(...$suppressed);
+ }
+}
+```
+
+Usage is then
+
+```php
+throw new EventPropagationFailedException(...$suppressedExceptions);
+```
+
+
+**TODO: screenshot from debugger** how it looks when catched
+
+
+
+## More reading
+
+- https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html#suppressed-exceptions
+
-```
\ No newline at end of file
--
GitLab