Whoops

https://github.com/filp/whoops
Admin
Whoops is an error handler framework for PHP that provides a beautiful error interface and flexible...
Tokens:86,678
Snippets:672
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Use PrettyPageHandler with Run; capture page via handleException

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Shows two usage scenarios for PrettyPageHandler: the basic setup registers the handler with Run and enables Whoops, while the second example captures the rendered HTML page by disabling output and quitting, then calls handleException to get the string. Use the second when you need to send the page yourself.

```php
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

$run = new Run();
$run->pushHandler(new PrettyPageHandler());
$run->register();
```

```php
$run = new Run();
$run->allowQuit(false);
$run->writeToOutput(false);
$run->pushHandler(new PrettyPageHandler());
$html = $run->handleException($e);   // string; no headers, no exit
```

--------------------------------

### composer.json for application using integration

Source: https://github.com/filp/whoops/blob/master/docs/Framework Integration.md

Example composer.json snippet showing how SomeFramework users would require the integration package, which also installs Whoops.

```json
    "require": {
        "username/whoops-someframework": "*"
    }
```

--------------------------------

### Example - annotate frames with map

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame-collection.md

Example from examples/example.php showing how to use map to add comments to frames. The callable must return the Frame; forgetting this throws UnexpectedValueException.

```php
$inspector->getFrames()->map(function ($frame) {
    if ($function = $frame->getFunction()) {
        $frame->addComment("This frame is within function '$function'", 'cpt-obvious');
    }
    return $frame;   // must return a Frame — forgetting this throws UnexpectedValueException
});
```

--------------------------------

### Editor as ajax (IntelliJ) example

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Example of setting an editor as an ajax resolver for the IntelliJ platform. The callback returns an array with 'url' and 'ajax' keys, enabling ajax-based editor opening.

```php
$handler->setEditor(function ($file, $line) {
    return [
        'url'  => "http://localhost:63342/api/file/?file=$file&line=$line",
        'ajax' => true,
    ];
});
```

--------------------------------

### Plain text output example

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/formatter.md

Example output of formatExceptionPlain. Frame numbering is #N where N = count(frames) - index - 1 (highest number first). Missing files render as <#unknown>; missing lines render as 0.

```text
RuntimeException thrown with message "Something broke!"

Stacktrace:
#3 SomeClass:method in /path/to/file.php:12
#2 otherFunction in /path/to/other.php:4
...
```

--------------------------------

### CLI/log-only setup with PlainTextHandler

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/plain-text-handler.md

Sets up Whoops with a PlainTextHandler that logs to a PSR-3 logger (e.g., Monolog). For web requests (non-command-line), it enables loggerOnly mode so errors are logged but not displayed. This is the CLI/log-only setup pattern from the API documentation.

```php
use Whoops\Run;
use Whoops\Handler\PlainTextHandler;
use Whoops\Util\Misc;

$plainTextHandler = new PlainTextHandler($logger);   // any PSR-3 logger, e.g. Monolog
if (!Misc::isCommandLine()) {
    $plainTextHandler->loggerOnly(true);             // web requests: log only
}
$run = new Run();
$run->pushHandler($plainTextHandler);
$run->register();
```

--------------------------------

### Install Whoops with Composer

Source: https://github.com/filp/whoops/blob/master/README.md

Installs Whoops into a project using Composer. This is the first step for projects not using a framework that already includes Whoops.

```bash
composer require filp/whoops
```

--------------------------------

### Construct Run with optional SystemFacade

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Constructor accepts an optional SystemFacade; the destructor calls unregister(). The example shows default construction and explicit facade construction.

```php
public function __construct(?SystemFacade $system = null)
```

```php
public function __destruct()        // calls $this->unregister()
```

```php
use Whoops\Run;
use Whoops\Util\SystemFacade;

$run = new Run();                          // default SystemFacade
$run = new Run(new SystemFacade());        // explicit (same behavior)
```

--------------------------------

### getFileLines method

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame.md

Returns an array of file lines starting at the zero-indexed $start, with $length lines (null means all). Returns null when file contents are unavailable. $start is clamped to >= 0; $length <= 0 throws InvalidArgumentException. Result keys preserve original line indexes.

```php
/**
 * @throws InvalidArgumentException if $length is less than or equal to 0
 */
public function getFileLines($start = 0, $length = null)   // → string[]|null   (line 198)
```

--------------------------------

### Example: hide sensitive request data

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Example usage to hide sensitive request data: blacklists '_GET' key 'token' and hides '_SERVER' key 'HTTP_AUTHORIZATION'.

```php
$handler = new PrettyPageHandler();
$handler->blacklist('_GET', 'token');
$handler->hideSuperglobalKey('_SERVER', 'HTTP_AUTHORIZATION');
```

--------------------------------

### Whoops\Util\SystemFacade

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/util.md

Documentation for the SystemFacade class, a thin wrapper over PHP global functions for whoops' system interactions. It lists all public methods with signatures, return types, and descriptions, plus an example of extending the class.

```APIDOC
## `Whoops\Util\SystemFacade`

Thin wrapper over PHP's global functions so whoops' system interactions are introspectable/replaceable. Injectable via `Run::__construct(?SystemFacade $system = null)` — extend it to override individual calls (see README).

- **Source:** `src/Whoops/Util/SystemFacade.php`
- **Declaration:** `class SystemFacade` (line 9)
- **Import path:** `Whoops\Util\SystemFacade`

| Method | Signature (source line) | Returns | Description |
|---|---|---|---|
| `startOutputBuffering` | `public function startOutputBuffering()` (16) | `bool` | `ob_start()` |
| `setErrorHandler` | `public function setErrorHandler(callable $handler, $types = 'use-php-defaults')` (27) | `callable\|null` | `set_error_handler`; `'use-php-defaults'` coerces to `E_ALL` |
| `setExceptionHandler` | `public function setExceptionHandler(callable $handler)` (41) | `callable\|null` | `set_exception_handler` |
| `restoreExceptionHandler` | `public function restoreExceptionHandler()` (49) | `void` | `restore_exception_handler()` |
| `restoreErrorHandler` | `public function restoreErrorHandler()` (57) | `void` | `restore_error_handler()` |
| `registerShutdownFunction` | `public function registerShutdownFunction(callable $function)` (67) | `void` | `register_shutdown_function` |
| `cleanOutputBuffer` | `public function cleanOutputBuffer()` (75) | `string\|false` | `ob_get_clean()` |
| `getOutputBufferLevel` | `public function getOutputBufferLevel()` (83) | `int` | `ob_get_level()` |
| `endOutputBuffering` | `public function endOutputBuffering()` (91) | `bool` | `ob_end_clean()` |
| `flushOutputBuffer` | `public function flushOutputBuffer()` (99) | `void` | `flush()` |
| `getErrorReportingLevel` | `public function getErrorReportingLevel()` (107) | `int` | `error_reporting()` |
| `getLastError` | `public function getLastError()` (115) | `array\|null` | `error_get_last()` |
| `setHttpResponseCode` | `public function setHttpResponseCode($httpCode)` (125) | `int` | `http_response_code($httpCode)`; also `header_remove('location')` when headers not yet sent |
| `stopExecution` | `public function stopExecution($exitStatus)` (140) | `void` | `exit($exitStatus)` |

**Example — custom façade (README pattern):**

```php
use Whoops\Run;
use Whoops\Util\SystemFacade;

class MySystemFacade extends SystemFacade
{
    public function stopExecution($exitStatus)
    {
        // never let the process die; log instead
        error_log("whoops wanted to exit with $exitStatus");
    }
}

$run = new Run(new MySystemFacade());
```
```

--------------------------------

### getFileLines usage example

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame.md

Example usage of getFileLines: retrieves the first frame from the inspector and gets a single line (line 9, zero-indexed) from the file, returning an array with key 9.

```php
$frame = $inspector->getFrames()[0];
$lines = $frame->getFileLines(9, 1);   // array(9 => '...')
```

--------------------------------

### Whoops\Util\TemplateHelper

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/util.md

Documentation for the Whoops\Util\TemplateHelper class, including its constructor, methods, and a usage example.

```APIDOC
## `Whoops\Util\TemplateHelper`

### Description
Template-rendering and escaping utilities consumed by `PrettyPageHandler` (passed to templates as the `$tpl` variable).

### Constructor

```php
public function __construct()
```

Sets the default application root path to `dirname()` repeated six levels up from the class directory (ordinary Composer project root).

### Methods

| Method | Signature | Returns | Description |
|---|---|---|---|
| `escape` | `public function escape($raw)` | `string` | `htmlspecialchars` with `ENT_QUOTES` (+ `ENT_SUBSTITUTE` unless HHVM, else `ENT_IGNORE`), UTF-8; tabs expanded to 4 spaces |
| `escapeButPreserveUris` | `public function escapeButPreserveUris($raw)` | `string` | `escape()` then linkify `http(s)://` URIs into `<a target="_blank" rel="noreferrer noopener">` anchors |
| `breakOnDelimiter` | `public function breakOnDelimiter($delimiter, $s)` | `string` | Wraps segments in `<span class="delimiter">…</span>` |
| `shorten` | `public function shorten($path)` | `string` | Replaces the application root path with `&hellip;` |
| `dump` | `public function dump($value)` | `string` | HTML dump via Symfony `HtmlDumper` (when var-dumper installed) or `htmlspecialchars(print_r(...))` fallback |
| `dumpArgs` | `public function dumpArgs(Frame $frame)` | `string` | `<ol class="linenums">` of dumped frame args; `''` when no dumper available |
| `slug` | `public function slug($original)` | `string` | Lowercased, space→dash, non-`[\w\d\-_]` stripped |
| `render` | `public function render($template, ?array $additionalVariables = null)` | `void` | Includes the template file with extracted variables, plus the helper as `$tpl` |
| `setVariables` | `public function setVariables(array $variables)` | `void` | Replaces all template variables |
| `setVariable` | `public function setVariable($variableName, $variableValue)` | `void` | Set single variable |
| `getVariable` | `public function getVariable($variableName, $defaultValue = null)` | `mixed` | Read single variable or `$defaultValue` |
| `delVariable` | `public function delVariable($variableName)` | `void` | Unset a variable |
| `getVariables` | `public function getVariables()` | `array` | All variables |
| `setCloner` | `public function setCloner($cloner)` | `void` | Set the Symfony `AbstractCloner` used by `dump()` |
| `getCloner` | `public function getCloner()` | `AbstractCloner` | Lazily creates a `VarCloner` |
| `setApplicationRootPath` | `public function setApplicationRootPath($applicationRootPath)` | `void` | Change root used by `shorten()` |
| `getApplicationRootPath` | `public function getApplicationRootPath()` | `string` | Current root |

### Example

```php
use Whoops\Util\TemplateHelper;

$helper = new TemplateHelper();
$helper->setVariables(['title' => 'Oops']);
$helper->render('/path/to/my-template.php', ['extra' => 'value']);

echo $helper->escape('<script>alert(1)</script>');   // &lt;script&gt;...
echo $helper->slug('What a Mess!');                  // "what-a-mess"
```
```

--------------------------------

### Echo formatExceptionPlain output

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/formatter.md

Example of calling formatExceptionPlain and echoing the result. The comment shows a sample output.

```php
echo Formatter::formatExceptionPlain($inspector);
// RuntimeException thrown with message "Oh fudge napkins!"
// Stacktrace: ...
```

--------------------------------

### Using Misc::isAjaxRequest, isCommandLine, translateErrorCode, and isLevelFatal

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/util.md

Example usage of Whoops\Util\Misc static methods. It shows how to conditionally push a JsonResponseHandler for AJAX requests, set loggerOnly(false) for command-line usage, and demonstrates translateErrorCode and isLevelFatal outputs.

```php
use Whoops\Util\Misc;

if (Misc::isAjaxRequest()) {
    $run->pushHandler(new JsonResponseHandler());
}
if (Misc::isCommandLine()) {
    $textHandler->loggerOnly(false);
}
var_dump(Misc::translateErrorCode(E_WARNING));   // "E_WARNING"
var_dump(Misc::isLevelFatal(E_ERROR));           // true
```

--------------------------------

### FrameCollection

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame-collection.md

Documentation for the FrameCollection class, including its methods and a usage example.

```APIDOC
## FrameCollection

### Description
Represents a collection of exception frames. Provides methods to count, access, and filter frames.

### Methods

#### count()
Returns the number of frames in the collection. Implements Countable.

#### offsetGet($index)
Returns the frame at the given index. Implements ArrayAccess.

#### countIsApplication()
Returns the number of frames that are application frames.

#### filter(callable $callback)
Filters the collection using the provided callback. Returns the same collection, now filtered.

### Usage Example
```php
use Whoops\Exception\FrameCollection;

/** @var FrameCollection $frames */
$frames = $inspector->getFrames();

$count = count($frames);                          // Countable
$first = $frames[0];                              // ArrayAccess read
echo $frames->countIsApplication();

$appFrames = $frames->filter(function ($frame) {
    return $frame->isApplication();
});   // returns the same collection, now filtered
```
```

--------------------------------

### PlainTextHandler

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/plain-text-handler.md

Documentation for the PlainTextHandler class, including constructor, methods, and usage examples.

```APIDOC
## PlainTextHandler

### Description
Creates a plain text error handler that can be used to log errors to a PSR-3 logger or output them as plain text. It supports configuration for including trace information, function arguments, and previous exceptions.

### Constructor
`new PlainTextHandler($logger = null)`

- **$logger** (Psr\Log\LoggerInterface|null) - Optional PSR-3 logger instance. If provided, errors will be logged to it. If not provided, output will be plain text.

### Methods

#### `loggerOnly(bool $loggerOnly)`
- **$loggerOnly** (bool) - When true, the handler will only log errors to the logger and not output them. Useful for web requests.

#### `addTraceToOutput(bool $addTraceToOutput)`
- **$addTraceToOutput** (bool) - When true, adds the stack trace to the output.

#### `addTraceFunctionArgsToOutput(int $numArgs)`
- **$numArgs** (int) - Number of stack frames to include function arguments for. Set to 0 to disable.

#### `setTraceFunctionArgsOutputLimit(int $limit)`
- **$limit** (int) - Maximum number of bytes to dump for each function argument. Oversized arguments are replaced with a discard notice.

#### `addPreviousToOutput(bool $addPreviousToOutput)`
- **$addPreviousToOutput** (bool) - When true, chains previous exceptions to the output.

#### `setDumper(callable $dumper)`
- **$dumper** (callable) - Custom function to dump variable values. Receives the variable and should output the dump.

### Usage Example
```php
use Whoops\Run;
use Whoops\Handler\PlainTextHandler;
use Whoops\Util\Misc;

$plainTextHandler = new PlainTextHandler($logger);   // any PSR-3 logger, e.g. Monolog
if (!Misc::isCommandLine()) {
    $plainTextHandler->loggerOnly(true);             // web requests: log only
}
$run = new Run();
$run->pushHandler($plainTextHandler);
$run->register();
```

### Advanced Usage Example
```php
use Whoops\Handler\PlainTextHandler;

$handler = new PlainTextHandler();
$handler->addTraceToOutput(true);
$handler->addTraceFunctionArgsToOutput(3);     // dump args of first 3 frames only
$handler->setTraceFunctionArgsOutputLimit(512);
$handler->addPreviousToOutput(true);

// Custom argument dumper:
$handler->setDumper(function ($var) {
    echo json_encode($var);
});
```

### Error Handling
- `handle()` never throws exceptions.
- Constructor and setters may throw `InvalidArgumentException` for a wrong logger type.
- Oversized argument dumps are silently replaced with a discard notice.
```

--------------------------------

### Capture HTML without quitting using handleException

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Use this example to capture the HTML output of Whoops without sending it to the browser. It disables quitting and output writing, pushes a PrettyPageHandler, and calls handleException to return the page as a string instead of echoing it.

```php
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

$whoops = new Run;
$whoops->allowQuit(false);
$whoops->writeToOutput(false);
$whoops->pushHandler(new PrettyPageHandler);

$html = $whoops->handleException($e);   // returns the page instead of echoing
```

--------------------------------

### Using InspectorFactory to create an inspector

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/inspector-factory.md

Example of using the default InspectorFactory to create an inspector for an exception and retrieve its name. This is the default behavior when using Whoops.

```php
use Whoops\Inspector\InspectorFactory;

$factory = new InspectorFactory();
$inspector = $factory->create($e);      // Whoops\Exception\Inspector
echo $inspector->getExceptionName();
```

--------------------------------

### Custom InspectorFactory implementation and usage

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/inspector-factory.md

Example of plugging a custom factory into Run. The custom factory caches inspectors by exception object hash. This demonstrates how to implement InspectorFactoryInterface and set it on a Run instance.

```php
use Whoops\Run;
use Whoops\Inspector\InspectorFactoryInterface;
use Whoops\Inspector\InspectorInterface;
use Whoops\Exception\Inspector;

class CachingInspectorFactory implements InspectorFactoryInterface
{
    private $cache = [];
    public function create($exception): InspectorInterface
    {
        $key = spl_object_hash($exception);
        return $this->cache[$key] ?? ($this->cache[$key] = new Inspector($exception, $this));
    }
}

$run = new Run();
$run->setInspectorFactory(new CachingInspectorFactory());
```

--------------------------------

### CallbackHandler predicate guard example

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/handler.md

Shows how to guard inside a callback because throwing inside a callback aborts the whole handler walk. It claims only MyApiException instances, returns Handler::QUIT to stop, and otherwise returns Handler::DONE to let other handlers run.

```php
use Whoops\Handler\Handler;

$run->pushHandler(function ($exception, $inspector, $run) {
    // Only claim AJAX-style exceptions; otherwise remain silent:
    if ($exception instanceof MyApiException) {
        http_response_code(422);
        echo json_encode(['error' => $exception->getMessage()]);
        return Handler::QUIT;
    }
    return Handler::DONE;
});
```

--------------------------------

### composer.json for integration package

Source: https://github.com/filp/whoops/blob/master/docs/Framework Integration.md

Example composer.json for a Whoops integration package. Requires filp/whoops version 1.*.

```json
{
    "name": "username/whoops-someframework",
    "description": "Integrates the Whoops library into SomeFramework",
    "require": {
        "filp/whoops": "1.*"
    }
}
```

--------------------------------

### Custom inspector factory with setInspectorFactory

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Shows how to inject a custom InspectorFactoryInterface implementation into a Whoops Run instance. The factory's create method must return an InspectorInterface, and the example defines a MyFactory class that implements the interface.

```php
use Whoops\Run;
use Whoops\Inspector\InspectorFactoryInterface;
use Whoops\Inspector\InspectorInterface;

class MyFactory implements InspectorFactoryInterface {
    public function create($exception): InspectorInterface {
        // return a custom InspectorInterface implementation
    }
}

$run = new Run;
$run->setInspectorFactory(new MyFactory);
```

--------------------------------

### Basic usage with trace output

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/xml-response-handler.md

Basic usage: creates a Run, adds an XmlResponseHandler with trace output enabled, pushes it, and registers.

```php
use Whoops\Run;
use Whoops\Handler\XmlResponseHandler;

$run = new Run();
$handler = new XmlResponseHandler();
$handler->addTraceToOutput(true);
$run->pushHandler($handler);
$run->register();
```

--------------------------------

### JsonResponseHandler JSON payload format

Source: https://github.com/filp/whoops/blob/master/docs/API Documentation.md

Example JSON payload produced by JsonResponseHandler. The trace array is only included when addTraceToOutput(true) is set. The comment lines are part of the example.

```json
{
  "error": {
    "type": "RuntimeException",
    "message": "Something broke!",
    "file": "/var/project/foo/bar.php",
    "line": 22,

     # if JsonResponseHandler::addTraceToOutput(true):
     "trace": [
        { "file": "/var/project/foo/index.php",
          "line": 157,
          "function": "handleStuffs",
          "class": "MyApplication\DoerOfThings",
          "args": [ true, 10, "yay method arguments" ] },
        # ... more frames here ...
     ]
  }
}
```

--------------------------------

### Walking frames and previous exceptions with Inspector

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/inspector.md

Shows how to instantiate Inspector, print exception name and message, iterate over frames, and access previous exception inspector for chain support.

```php
use Whoops\Exception\Inspector;

$inspector = new Inspector($e);

echo $inspector->getExceptionName();       // e.g. "RuntimeException"
echo $inspector->getExceptionMessage();

foreach ($inspector->getFrames() as $frame) {
    printf("%s:%d %s%s()\n", $frame->getFile(), $frame->getLine(),
           $frame->getClass(), $frame->getFunction());
}

if ($inspector->hasPreviousException()) {
    $prev = $inspector->getPreviousExceptionInspector();
    echo $prev->getExceptionName();        // chain support
}
```

--------------------------------

### Initialize whoops with PrettyPageHandler

Source: https://github.com/filp/whoops/blob/master/_autodocs/README.md

Sets up the whoops error handler by creating a Run instance, pushing a PrettyPageHandler, and registering the handlers. This is the idiomatic entry point for using whoops in a PHP application.

```php
$whoops = new \Whoops\Run;
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$whoops->register();
```

--------------------------------

### getEditorAjax

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Gets the ajax flag for an editor.

```APIDOC
## getEditorAjax

### Description
Resolves the `ajax` flag for a given file and line. Returns `false` when no editor resolves.

### Method
getEditorAjax

### Signature
`public function getEditorAjax($filePath, $line)`

### Parameters
- `$filePath` (string) - Required - Absolute path of the file to open
- `$line` (int) - Required - Line number

### Throws
- `UnexpectedValueException` - If `ajax` is missing or not a bool

### Returns
- bool - The resolved `ajax` flag

### Example
```php
$handler->setEditor(function ($file, $line) {
    return [
        'url'  => "http://localhost:63342/api/file/?file=$file&line=$line",
        'ajax' => true,
    ];
});
```
```

--------------------------------

### Render a custom template with TemplateHelper

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/util.md

Shows how to instantiate TemplateHelper, set variables, render a template, and use escape and slug methods. The escape method converts special characters to HTML entities, and slug converts a string to a URL-friendly format.

```php
use Whoops\Util\TemplateHelper;

$helper = new TemplateHelper();
$helper->setVariables(['title' => 'Oops']);
$helper->render('/path/to/my-template.php', ['extra' => 'value']);

echo $helper->escape('<script>alert(1)</script>');   // &lt;script&gt;...
echo $helper->slug('What a Mess!');                  // "what-a-mess"
```

--------------------------------

### handleUnconditionally

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Gets or sets the handleUnconditionally flag.

```APIDOC
## handleUnconditionally

### Description
Getter/setter for the `handleUnconditionally` flag. When set to `true`, the CLI/premature-return logic in `handle()` is skipped.

### Method
handleUnconditionally

### Signature
`public function handleUnconditionally($value = null)`

### Parameters
- `$value` (mixed) - Optional - If provided, casts to bool and stores it

### Returns
- bool|static - If no arguments, returns the stored flag (default `false`); otherwise returns `$this` for chaining
```

--------------------------------

### Instantiate Whoops\Run with default or custom SystemFacade

Source: https://github.com/filp/whoops/blob/master/_autodocs/configuration.md

Shows two ways to instantiate the Whoops\Run class: with the default SystemFacade or with a custom facade. The custom facade is used to override system calls like set_error_handler, output buffering, HTTP codes, and exit().

```php
$run = new Run();                       // default façade
$run = new Run(new MySystemFacade());   // custom façade (see README "override system calls")
```

--------------------------------

### getApplicationPaths and setApplicationPaths signatures

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Paths used to mark frames as 'application' frames (prefix match on Frame::getFile()), switching the default frames tab to 'application' when any frame qualifies. See getExceptionFrames() (line 308).

```php
public function getApplicationPaths()                      // → array   (line 752)
public function setApplicationPaths(array $applicationPaths)   // → void   (line 762)
```

--------------------------------

### setPageTitle / getPageTitle

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Sets or gets the page title.

```APIDOC
## setPageTitle / getPageTitle

### Description
Sets or gets the page title for the error page. The default title is `"Whoops! There was an error."`.

### Method
setPageTitle / getPageTitle

### Signatures
- `public function setPageTitle($title)`
- `public function getPageTitle()`

### Parameters
- `$title` (string) - Required (for setPageTitle) - The page title

### Returns
- setPageTitle: static - Returns `$this` for chaining
- getPageTitle: string - The current page title

### Example
```php
$handler->setPageTitle('Custom Error');
$title = $handler->getPageTitle();
```
```

--------------------------------

### getEditorHref

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Gets the editor URL for a file and line.

```APIDOC
## getEditorHref

### Description
Resolves the editor URL for a given file and line. Returns `false` when no editor resolves.

### Method
getEditorHref

### Signature
`public function getEditorHref($filePath, $line)`

### Parameters
- `$filePath` (string) - Required - Absolute path of the file to open
- `$line` (int) - Required - Line number

### Throws
- `UnexpectedValueException` - If the resolved value is not a string in `url`

### Returns
- string|bool - The editor URL or `false` if no editor resolves
```

--------------------------------

### handle() implementation

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/xml-response-handler.md

Builds the response array using Formatter::formatExceptionAsDataArray, converts it to XML with toXml(), echoes it, and returns Handler::QUIT.

```php
$response = [
    'error' => Formatter::formatExceptionAsDataArray(
        $this->getInspector(),
        $this->addTraceToOutput(),
        $this->getRun()->getFrameFilters()
    ),
];
echo self::toXml($response);
return Handler::QUIT;
```

--------------------------------

### handle

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/json-response-handler.md

Builds the response, encodes it as JSON, echoes it, and returns Handler::QUIT to terminate execution.

```APIDOC
## handle

### Description
Builds the response, encodes it with `json_encode($response, defined('JSON_PARTIAL_OUTPUT_ON_ERROR') ? JSON_PARTIAL_OUTPUT_ON_ERROR : 0)`, `echo`es it, and returns `Handler::QUIT`.

### Method
handle

### Signature
public function handle() : int

### Returns
- **int** - Returns `Handler::QUIT` to terminate execution.

### Response Shape (non-JSON:API)
```json
{
  "error": {
    "type": "RuntimeException",
    "message": "Something broke!",
    "code": 0,
    "file": "/var/project/foo/bar.php",
    "line": 22,
    "trace": [
      {
        "file": "/var/project/index.php",
        "line": 157,
        "function": "handleStuffs",
        "class": "MyApplication\\DoerOfThings",
        "args": [true, 10, "yay method arguments"]
      }
    ]
  }
}
```

### Response Shape (JSON:API)
```json
{
  "errors": [
    { "type": "...", "message": "...", "code": 0, "file": "...", "line": 22 }
  ]
}
```

### Field Semantics
- **type** (string) - Fully-qualified exception class name (`get_class($exception)`)
- **message** (string) - `$exception->getMessage()`
- **code** (int) - `$exception->getCode()`
- **file** (string) - `$exception->getFile()`
- **line** (int) - `$exception->getLine()`
- **trace** (array) - Only when `addTraceToOutput(true)`; each entry has `file`, `line`, `function`, `class`, `args` per frame
```

--------------------------------

### Push a closure as a CallbackHandler

Source: https://github.com/filp/whoops/blob/master/docs/API Documentation.md

Shows how to push a closure as a handler. The closure receives the exception, inspector, and run instance; returning Handler::DONE indicates the handler has processed the exception. After pushing, popHandler() returns a CallbackHandler instance.

```php
<?php

use Whoops\Handler\Handler;

$run->pushHandler(function($exception, $inspector, $run) {
    var_dump($exception->getMessage());
    return Handler::DONE;
});

$run->popHandler() // #=> Whoops\Handler\CallbackHandler
```

--------------------------------

### Run::__construct

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Constructor for the Run class, allowing optional injection of a SystemFacade.

```APIDOC
## Constructor

### Description
Initializes a new Run instance, optionally with a custom SystemFacade.

### Method
__construct

### Signature
```php
public function __construct(?SystemFacade $system = null)
```

### Parameters
- `$system` (?Whoops\Util\SystemFacade) - Optional - System-call façade; override to intercept `set_error_handler`, output buffering, `exit`, etc. Defaults to `null` (→ `new SystemFacade`).

### Example
```php
use Whoops\Run;
use Whoops\Util\SystemFacade;

$run = new Run();                          // default SystemFacade
$run = new Run(new SystemFacade());        // explicit (same behavior)
```
```

--------------------------------

### writeToOutput

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Gets or sets whether handler output is echoed directly. When false, handleException() returns the output instead.

```APIDOC
## writeToOutput

### Description
Gets or sets whether handler output is echoed directly. When false, handleException() returns the output instead.

### Method
writeToOutput

### Signature
public function writeToOutput($send = null)

### Parameters
- $send (bool|int) - Optional - If true, handler output is echoed directly; if false, handleException() returns it. Default stored value: true.

### Returns
bool
```

--------------------------------

### setApplicationRootPath method signature

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Delegates to TemplateHelper::setApplicationRootPath() to shorten paths in rendered output.

```php
public function setApplicationRootPath($applicationRootPath)   // → void   (line 774)
```

--------------------------------

### PlainTextHandler setTraceFunctionArgsOutputLimit and getTraceFunctionArgsOutputLimit methods

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/plain-text-handler.md

Set and get the maximum bytes for a frame-args dump. Default is 1024; larger dumps are discarded.

```php
public function setTraceFunctionArgsOutputLimit($traceFunctionArgsOutputLimit)   // → static   (line 165)
public function getTraceFunctionArgsOutputLimit()                              // → int       (line 198)
```

--------------------------------

### handleException

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Documentation for the handleException method of the Whoops Run class.

```APIDOC
## handleException

### Description
Handles an exception by building an inspector, running all registered handlers, and returning the generated output. This is the main dispatch method for the Whoops error handler.

### Method
handleException

### Signature
public function handleException($exception) : string

### Parameters
- **$exception** (Throwable) - Required - The exception (or error) to handle.

### Behavior
1. Builds the inspector via the configured InspectorFactoryInterface.
2. Starts output buffering (SystemFacade::startOutputBuffering()).
3. Iterates array_reverse($this->handlerStack); for each handler calls setRun, setInspector, setException, then handle($exception); collects contentType() if the handler has such a method.
4. Breaks the loop when a handler returns Handler::LAST_HANDLER or Handler::QUIT. $willQuit = $handlerResponse == Handler::QUIT && $this->allowQuit().
5. Cleans the output buffer in a finally block.
6. If writeToOutput(): cleans nested buffers when quitting, sends Content-Type header (when Misc::canSendHeaders() and a content type was collected), then echoes output — setting the HTTP code via sendHttpCode() first.
7. If $willQuit: flushes output and calls SystemFacade::stopExecution($this->sendExitCode()) (exit()).
8. Always returns the generated output string.

### Example — capture HTML without quitting
```php
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

$whoops = new Run;
$whoops->allowQuit(false);
$whoops->writeToOutput(false);
$whoops->pushHandler(new PrettyPageHandler);

$html = $whoops->handleException($e);   // returns the page instead of echoing
```
```

--------------------------------

### sendHttpCode

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Gets or sets the HTTP status code sent with the error response. The setter validates the code and throws an exception for invalid values.

```APIDOC
## sendHttpCode

### Description
Gets or sets the HTTP status code sent with the error response. The setter validates the code and throws an exception for invalid values.

### Method
sendHttpCode

### Signature
public function sendHttpCode($code = null)

### Parameters
- $code (bool|int) - Optional - HTTP status code sent with the error response. Default stored value: 500.

### Returns
int|false

### Throws
- InvalidArgumentException if code is < 400 or >= 600.

### Behavior
- null (no args): returns current value.
- falsy (0, false, '', ...): sets to false (send no HTTP code).
- true: coerced to 500.
- < 400 or >= 600: throws InvalidArgumentException with message "Invalid status code '$code', must be 4xx or 5xx".
```

--------------------------------

### sendExitCode

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Gets or sets the exit status used when the handler terminates the CLI process. The setter validates the code and throws an exception for invalid values.

```APIDOC
## sendExitCode

### Description
Gets or sets the exit status used when the handler terminates the CLI process. The setter validates the code and throws an exception for invalid values.

### Method
sendExitCode

### Signature
public function sendExitCode($code = null)

### Parameters
- $code (int) - Optional - Exit status used when Handler::QUIT terminates the CLI process. Default stored value: 1.

### Returns
int

### Throws
- InvalidArgumentException if code < 0 or >= 255.

### Behavior
- null (no args): returns current value.
- Throws InvalidArgumentException with message "Invalid status code '$code', must be between 0 and 254".
```

--------------------------------

### Whoops\RunInterface

Source: https://github.com/filp/whoops/blob/master/_autodocs/types.md

Documentation for the Whoops\RunInterface, including its constants and method signatures.

```APIDOC
## Whoops\RunInterface

### Description
Defines the contract for the main Whoops error handler. It declares constants for handler names and the methods that any implementation must provide.

### Constants
- **EXCEPTION_HANDLER** (string) - "handleException"
- **ERROR_HANDLER** (string) - "handleError"
- **SHUTDOWN_HANDLER** (string) - "handleShutdown"

### Methods

#### pushHandler
- **Signature:** `public function pushHandler($handler);`
- **Returns:** `Run`
- **Throws:** `InvalidArgumentException`

#### popHandler
- **Signature:** `public function popHandler();`
- **Returns:** `null|HandlerInterface`

#### getHandlers
- **Signature:** `public function getHandlers();`
- **Returns:** `array`

#### clearHandlers
- **Signature:** `public function clearHandlers();`
- **Returns:** `Run`

#### getFrameFilters
- **Signature:** `public function getFrameFilters();`
- **Returns:** `array<callable>`

#### clearFrameFilters
- **Signature:** `public function clearFrameFilters();`
- **Returns:** `Run`

#### register
- **Signature:** `public function register();`
- **Returns:** `Run`

#### unregister
- **Signature:** `public function unregister();`
- **Returns:** `Run`

#### allowQuit
- **Signature:** `public function allowQuit($exit = null);`
- **Returns:** `bool`

#### silenceErrorsInPaths
- **Signature:** `public function silenceErrorsInPaths($patterns, $levels = 10240);`
- **Returns:** `Run`

#### sendHttpCode
- **Signature:** `public function sendHttpCode($code = null);`
- **Returns:** `int|false`

#### sendExitCode
- **Signature:** `public function sendExitCode($code = null);`
- **Returns:** `int`

#### writeToOutput
- **Signature:** `public function writeToOutput($send = null);`
- **Returns:** `bool`

#### handleException
- **Signature:** `public function handleException($exception);`
- **Returns:** `string`

#### handleError
- **Signature:** `public function handleError($level, $message, $file = null, $line = null);`
- **Returns:** `bool`
- **Throws:** `ErrorException`

#### handleShutdown
- **Signature:** `public function handleShutdown();`
- **Returns:** `void`

#### addFrameFilter
- **Signature:** `public function addFrameFilter($filterCallback);`
- **Returns:** `Run`
- **Throws:** `InvalidArgumentException`
```

--------------------------------

### allowQuit

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/run.md

Gets or sets whether handlers may force script termination. When called with no arguments, it returns the current value; otherwise it casts the argument to boolean and stores it.

```APIDOC
## allowQuit

### Description
Gets or sets whether handlers may force script termination. When called with no arguments, it returns the current value; otherwise it casts the argument to boolean and stores it.

### Method
allowQuit

### Signature
public function allowQuit($exit = null)

### Parameters
- $exit (bool|int) - Optional - Whether handlers may force script termination. Default stored value: true.

### Returns
- bool (getter) | bool (setter result)

### Behavior
- No arguments: returns current value.
- With argument: casts to (bool) and stores it.
- When false, a Handler::QUIT response degrades to Handler::LAST_HANDLER behavior.
```

--------------------------------

### handle method signature

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/json-response-handler.md

Builds the response, encodes it with json_encode, echoes it, and returns Handler::QUIT. The encoding uses JSON_PARTIAL_OUTPUT_ON_ERROR if defined.

```php
public function handle()   // → int (Handler::QUIT)   (line 56)
```

--------------------------------

### JSON:API response shape

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/json-response-handler.md

Example JSON response shape when setJsonApi(true) is used. The error object is wrapped in an 'errors' array per the JSON:API spec.

```json
{
  "errors": [
    { "type": "...", "message": "...", "code": 0, "file": "...", "line": 22 }
  ]
}
```

--------------------------------

### getFile method

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame.md

Returns the frame's file path, or null if not set. When $shortened is true, replaces the common project root with an ellipsis and inserts soft-hyphens after slashes. Normalizes eval()'d/assert code frames by extracting the path and line from the parentheses.

```php
public function getFile($shortened = false)   // → string|null   (line 43)
```

--------------------------------

### Non-JSON:API response shape

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/json-response-handler.md

Example JSON response shape when not using JSON:API mode. The 'error' object contains type, message, code, file, line, and optionally a trace array.

```json
{
  "error": {
    "type": "RuntimeException",
    "message": "Something broke!",
    "code": 0,
    "file": "/var/project/foo/bar.php",
    "line": 22,
    "trace": [
      {
        "file": "/var/project/index.php",
        "line": 157,
        "function": "handleStuffs",
        "class": "MyApplication\\DoerOfThings",
        "args": [true, 10, "yay method arguments"]
      }
    ]
  }
}
```

--------------------------------

### Catching Whoops\Exception\ErrorException

Source: https://github.com/filp/whoops/blob/master/_autodocs/errors.md

Shows how consumer code catches Whoops\Exception\ErrorException. The severity and code are the same value (BC duplication). Because Run::register() installs an error handler, PHP errors are converted into this class before reaching the exception handler.

```php
try {
    // code that may trigger a PHP-level error while whoops is registered
} catch (\Whoops\Exception\ErrorException $e) {
    $severity = $e->getSeverity();        // the original PHP error level
    $code     = $e->getCode();            // same value (BC duplication)
} catch (\Throwable $e) {
    // any other exception
}

```

--------------------------------

### equals method

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame.md

Returns true when both frames have the same file and line. Always false if this frame's file is missing, 'Unknown', or line is missing.

```php
public function equals(Frame $frame)   // → bool   (line 284)
```

--------------------------------

### Custom JSON handler using formatExceptionAsDataArray

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/formatter.md

Example of a custom JSON handler that reuses the formatter. It passes the inspector, true for $shouldAddTrace, and the run's frame filters, then logs the JSON-encoded data and returns Handler::DONE.

```php
use Whoops\Exception\Formatter;
use Whoops\Handler\Handler;
use Whoops\Run;

$run->pushHandler(function ($exception, $inspector, $run) use ($logger) {
    $data = Formatter::formatExceptionAsDataArray($inspector, true, $run->getFrameFilters());
    $logger->error(json_encode($data));
    return Handler::DONE;
});
```

--------------------------------

### getApplicationPaths / setApplicationPaths

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/pretty-page-handler.md

Manages application paths for frame classification.

```APIDOC
## `getApplicationPaths` / `setApplicationPaths`

### Description
Gets or sets the application paths used to mark frames as application frames. When any frame matches, the default frames tab switches to 'application'.

### Methods
- `public function getApplicationPaths()`
- `public function setApplicationPaths(array $applicationPaths)`

### Parameters (setApplicationPaths)
- **$applicationPaths** (array) - Required - List of paths to mark as application paths.

### Return Value
- `getApplicationPaths()`: array - The application paths.
- `setApplicationPaths()`: void

### Example
```php
$paths = $handler->getApplicationPaths();
$handler->setApplicationPaths(['/app']);
```
```

--------------------------------

### PlainTextHandler handle method

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/plain-text-handler.md

Generates the response, logs it if a logger is set, and either echoes and returns QUIT or returns DONE when loggerOnly is true.

```php
public function handle()   // → int (Handler::DONE|Handler::QUIT)   (line 335)
```

--------------------------------

### Handle unreadable frame files (PHP)

Source: https://github.com/filp/whoops/blob/master/_autodocs/api-reference/frame.md

Use this snippet to safely retrieve lines from a frame's file. It attempts to get 50 lines, catches an InvalidArgumentException for non-positive lengths, and retries with 10 lines. A null result indicates the file is unknown, internal, or unreadable.

```php
$file = $frame->getFile();
$lines = null;
try {
    $lines = $frame->getFileLines(0, 50);
} catch (\InvalidArgumentException $e) {
    // $length was <= 0 — request a positive line count
    $lines = $frame->getFileLines(0, 10);
}
if ($lines === null) {
    // frame file is unknown, internal, or unreadable
}
```
Tokens:
Raw