grifart/suppressed-exceptions

Adds support for suppressed exceptions as known in Java. https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html#suppressed-exceptions

v0.2.2 2022-03-17 14:18 UTC

Requires

• php: ~7.1.0 || ~7.2.0 || ~7.3.0 || ~7.4.0 || ^8.0

Requires (Dev)

• grifart/phpstan-oneline: ^0.4.0
• nette/tester: ^2.1
• php-parallel-lint/php-console-highlighter: ^0.5.0
• php-parallel-lint/php-parallel-lint: ^1.2
• phpstan/phpstan: ^1.4

MIT

• Jan Kuchař

README

Suppressed exceptions are useful for aggregating more exceptions from unreliable resources.

Useful when you want to communicate that process failed, with a list of sibling exceptions that led to an error.

repositories:

• Grifart GitLab
• GitHub (mirror)

Example usage

$remoteSources = []; // classes representing unreliable remote sources

$exceptions = [];
foreach ($remoteSoures as $remoteSource) {
	try {
		$remoteSource->fetch(); // unsafe operation
	} catch (FetchingFailed $e) {
		$exceptions[] = $e;
		continue;
	}
}

if (count($exceptions) > 0) {
	$e = new ProcessingFailed();
	$e->addSuppressed(...$exceptions);
	throw $e;
}

You can also override exception constructor to provide better API

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

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