ForgeDebugBar

Overview

ForgeDebugBar is the debugging companion for your app. When enabled, it automatically injects a slim, tabbed toolbar into each HTML response. You keep your markup untouched — the bar is appended just before </body> along with its own CSS and a small bit of JavaScript.

It's built around collectors: small pieces of code, each responsible for one slice of data (memory, request time, messages, route, session, and — when the router capability is around — timeline, views, exceptions, and database queries). Collectors feed the tabbed panels, so you see what happened on the request you're looking at.

Installation

php forge.php package:install-module --module=forge-debug-bar

The capability needs the router and view capabilities present, and it links its public assets (the CSS and JS the bar uses) during installation:

php forge.php asset:link --type=module --module=forge-debug-bar

This makes the assets available at /assets/modules/forge-debug-bar/ so the injected toolbar can load them.

When the Bar Shows

The bar only appears when both of these are true:

• APP_DEBUG is enabled in your environment.
• forge_debug_bar.enabled is true (the default).

On top of that, injection is careful about what it touches. It skips:

• Responses whose Content-Type isn't HTML (for example JSON or files).
• Bodies that don't contain a </body> tag.
• Responses that look like a fragment, such as a leading {"html":.

The Bar & Tabs

The toolbar has a compact header that shows the essentials at a glance, then a set of tabs you can click to open full panels:

The Resources tab (memory panel) is always registered. The rest open up when metrics are enabled:

Each tab shows a small count badge when it has data, so you can spot at a glance which panels have something interesting.

Collectors

Collectors are the guts of the bar. Each is a named unit that returns the data for one panel when asked. A few of the built-in ones are always active:

When metrics are enabled, the bar also adds cross-module collectors provided by the router capability — timeline, views, exceptions, and database queries — but only for the ones actually available in your app. If a collector isn't present, its tab simply stays empty.

For custom needs, you can drop in your own collector by pairing a name with a callable that returns its data:

$bar = \Modules\ForgeDebugBar\DebugBar::getInstance();

$bar->addCollector('my-plugin', function () {
    return ['calls' => MyService::callCount()];
});

Custom Messages

The most common way to use the bar from your own code is the debug_log() helper. It records a message (with an optional label) that shows up in the Console tab on the current request:

debug_log('Order #123 placed', 'info');
debug_log($shippingTotal, 'amount');

Messages carry a label (default info) and a timestamp, so you can follow the sequence of events within a request.

A small formatBytes() helper is also available for turning byte counts into readable units (B, KB, MB, GB) in your own output.

Configuration

Two environment variables control the bar:

Turning metrics off is a quick way to keep the bar lightweight — the request, session, and route collectors plus the cross-module collectors and their tabs are simply skipped, along with the session-merge work that surfaces exceptions.

Safe in Production

Because the bar is gated on APP_DEBUG, a production environment with debugging off never renders it and never runs its collectors. Its public assets (a CSS file and a small JS file) can stay linked without impacting real users.