Repository navigation
Error Page
When something throws, blink stores a report and shows it. The report holds the exception, the stack trace with source, and the state of the request around it: headers, routing, modules, autoload, environment, queries, timings.
Reports live under DATA_ROOT/errors as {id}.report, and the Report-ID header names the one behind the response. /error/{id} renders it again later.
The response follows the Accept header:
| Accept | Response |
|---|---|
text/html first |
The error page |
application/json first |
The API envelope, with report pointing at the page |
Both carry the status, the code and the Report-ID header.
With CONFIG::$DEBUG off, the stored report keeps only the summary: the exception class, where it was thrown, and the request line. No headers, no session, no environment, no source. A report is reachable by anyone holding its id, so there is nothing sensitive in it to leak. The JSON envelope is redacted the same way: no exception section, no caller, no captured output.
A command that throws prints the same information as text on stderr: the exception, the location, the tip, the stack trace with the fault frame marked, and the report id at the bottom.
Blink\Exception\CodingError: Deliberate failure
at /routes/web.php:14
Stack trace:
> #0 /routes/web.php:14
Blink\Exception\CodingError()
#1 core/classes/Essence.php:385
App\Console\ImportOrders -> run()
Report 8daf2c816b8e621a4ebd
error:list finds it afterwards.
Some exceptions come with advice. Blink answers for its own:
| Exception | The tip says |
|---|---|
ClassNotDefined |
The file loaded but does not define the class, with a link to open it |
ClassNotFound |
Nothing loaded, and every path the autoloader tried |
RouteNotFound |
The path is not handled by the server |
InvalidDefinition |
What the class has to extend |
ModuleNotFound |
The module is listed in CONFIG::$MODULES but could not be loaded |
NotLoggedIn |
The page needs an authenticated session |
EtherInvalidMiddleware |
The reference is not a class, alias or group, and where to register it |
EssenceBindingNotDefined |
The abstract needs an Essence::bind() in a module's define()
|
CodingError for the user class |
Extend UserBase and register it with Blink::useUserClass()
|
An application adds its own:
use Blink\ErrorPage;
ErrorPage::addTipProvider(function (string $class, ?array $data) {
if ($class === App\Exception\QuotaExceeded::class)
return array( "Quota reached", "Raise the plan limit in settings." );
});Providers run after the built-ins, so one can speak to an exception blink already answers for.
The page ends with context groups: Request (path, method, status, query string, headers, body), App (routing, routes, session, modules, autoload, debug output, exception data, environments, constants, output buffer) and Metrics (requests, queries, files, a timeline of timings).
Add a group of your own:
ErrorPage::addContextProvider(function (ErrorPage $page) {
$group = new ContextGroup("Workspace");
$item = new ContextItem("current", "Current", Workspace::current() ?-> out(), "cube");
$item -> setRenderer([ ContextRenderer::class, "list" ]);
$group -> add($item);
return array( $group );
});Or through Ether's errorPage stage, which is the same thing wrapped in middleware and is what a module should prefer. See Ether. A provider that throws is logged and skipped: an error being reported must not be lost to a second one.
Work that fails with nobody to show a page to still files a report:
use Blink\ErrorPage;
try {
$importer -> run();
} catch (\Throwable $e) {
$id = ErrorPage::report($e);
Trace::error(Trace::APP, "import.failed") -> payload(array( "report" => $id )) -> record();
}A Ticker task that exhausts its attempts, an orbit entry that fails, and a Lightrail handler that throws all do this for you, and store the report id on the row so ticker:failed and lightrail:dispatch can point at it.
php core/blink error:list # server errors, from the index
php core/blink error:list --all # every report file, client errors included
php core/blink error:purge --days=30
php core/blink error:purge --keep=100 # keep the newest, delete the rest
Server errors are also appended to errors/meta.ndjson, a one-line-per-report index read backwards, so listing recent failures never unserializes anything. getMetas($amount, $page) reads it from code.
ErrorPage\Inspector turns a throwable into ErrorPage\Frame objects: one per trace entry, a synthetic frame in front for the throw site itself, the previous-exception chain merged in, and duplicate frames collapsed. Frames inside blink are badged blink and frames under vendor/ are badged vendor, so the application's own code is easy to pick out. Every throw site in the chain is badged fault.
A fatal error normally traces only to the shutdown handler. When Xdebug is loaded, its function stack is used instead, so the calls that led to the fatal are visible.