@ -59,6 +60,26 @@ Catcher comes built-in with the following handlers:
* `JSONHandler` – Outputs errors in a JSON format mostly representative of how errors are stored internally by Catcher handlers; it is provided as an example. The decision to make it like this was made because errors often need to be represented according to particular requirements or even a specification, and we cannot possibly support them all. `JSONHandler`, however, can be easily extended to suit individual project needs.
* `PlainTextHandler` – Outputs errors cleanly in plain text meant mostly for command line use and also provides for logging
### A Note About Warnings & Notices ###
As described in the summary paragraph at the beginning of this document, Catcher by default converts all warnings, notices, etc. to `Throwable`s and then proceeds to throw them. Normally, when throwing that halts execution no matter what, but with Catcher that is not the case.
```php
$catcher = new Catcher();
try {
trigger_error(\E_USER_WARNING, 'Ook!');
} catch (\Throwable $t) {
echo $t->message();
}
```
Output:
```
Ook!
```
This is accomplished internally because of [`pcntl_fork`][d]. The throw is done in a separate fork which causes that fork to exit after the `Throwable` is handled while the main process is allowed to continue. `pcntl_fork` is a POSIX function and therefore is only available for use in CLI UNIX environments; this means that it will work neither in Windows nor in Web environments. We also understand this might be undesirable behavior to some, so turning this off is as simple as setting `Catcher::$forking` to false.
## Documentation
@ -71,6 +92,7 @@ namespace MensBeam\Foundation;
use Mensbeam\Foundation\Catcher\Handler;
class Catcher {
public bool $forking = true;
public bool $preventExit = false;
public bool $throwErrors = true;
@ -91,6 +113,7 @@ class Catcher {
#### Properties
_forking_: When set to true Catcher will throw converted notices, warnings, etc. in a fork, allowing for execution to continue afterwards
_preventExit_: When set to true Catcher won't exit at all even after fatal errors or exceptions
_throwErrors_: When set to true Catcher will convert errors to throwables
@ -347,7 +370,7 @@ The default handlers, especially `PlainTextHandler`, are set up to handle most t
```php
namespace Your\Namespace\Goes\Here;
use Mensbeam\Foundation\Catcher\Handler,
use MensBeam\Foundation\Catcher\Handler,
Symfony\Component\Yaml\Yaml;
@ -389,7 +412,7 @@ class YamlHandler extends Handler {
This theoretical class uses the [`symfony/yaml`][c] package in Composer and exposes a few of its options as options for the Handler. Using this class would be very similar to the examples provided at the beginning of this document:
