Panel

API reference › Debug › Panel

class	`yii\debug\Panel`
Extends	`yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\ViewContextInterface`, `yii\base\Configurable`
Source	`src/Panel.php`

14 subclasses

Base class for debug toolbar panels.

Defines the contract every panel implements: how request data is captured, hydrated, and surfaced on the toolbar and detail views. The container Module wires $id, $module, and $tag automatically on registration.

Properties

Property	Type	Description	Defined by
`$actions`	`array<string, array<string, mixed>\|class-string>`	Standalone actions merged into the debug module’s `Module::$actionMap`, keyed by action ID. Default: `[]`.	`Panel`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$detail` read-only	`string`	Detail view markup; `''` when the panel does not expose a detail view.	`Panel`
`$id`	`string`	Panel unique identifier, assigned by the container module on registration. Default: `''`.	`Panel`
`$module`	`Module\|null`	Debug module owning this panel. Default: `null`.	`Panel`
`$name` read-only	`string`	Display name; `''` for the base class.	`Panel`
`$renderContext`	`PHPForge\Debug\Panel\PanelRenderContext\|null`	Prepared render context, or `null` outside a debugger request.	`Panel`
`$tag`	`string`	Tag of the request whose data this panel currently exposes. Default: `''`.	`Panel`
`$toolbarData` read-only	`array<string, mixed>`	Toolbar envelope; `[]` to skip the panel.	`Panel`
`$toolbarIcon` read-only	`string\|null`	Icon key, or `null` to render no icon.	`Panel`
`$url` read-only	`string`	Absolute URL to the panel detail view.	`Panel`
`$viewPath` read-only	`string`	Directory the panel views resolve against.	`Panel`
`$error` protected	`PHPForge\Debug\Storage\ExceptionSnapshot\|null`	Exception captured when the panel failed to produce or hydrate its snapshot. Default: `null`.	`Panel`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`capture()`	Captures the panel payload for the current request.	`Panel`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`getDetail()`	Returns the detail view markup rendered when the user opens the panel.	`Panel`
`getError()`	Returns the exception captured while collecting the panel payload, if any.	`Panel`
`getName()`	Returns the panel display name shown on the toolbar and the detail navigation.	`Panel`
`getRenderContext()`	Returns the framework-neutral render context for the active debugger request, when one has been prepared.	`Panel`
`getToolbarData()`	Returns the toolbar envelope wrapping the panel’s icon, items, and URL.	`Panel`
`getToolbarIcon()`	Returns the icon key used on the panel’s toolbar chip, or `null` to render no icon.	`Panel`
`getTraceLine()`	Builds a trace line for the toolbar through the shared `Trace` renderer, applying `Module::$tracePathMappings` and the configured `Module::$traceLine` template (or callable).	`Panel`
`getUrl()`	Returns the URL pointing to this panel’s detail view for the current request tag.	`Panel`
`getViewPath()`	Returns the directory under which the panel’s relative views resolve.	`Panel`
`hasContent()`	Returns whether the panel captured content for the loaded request.	`Panel`
`hasError()`	Returns `true` when `setError()` captured an exception during panel capture or hydration.	`Panel`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`hydrate()`	Hydrates the panel from the JSON payload previously produced by `capture()`.	`Panel`
`init()`	Initializes the object.	`yii\base\BaseObject`
`isEnabled()`	Indicates whether this panel is enabled and should be registered by the module.	`Panel`
`isVisible()`	Returns whether the panel should appear in the toolbar and sidebar navigation.	`Panel`
`moduleBound()`	Completes module-dependent wiring after the container module binds `$id` and `$module`.	`Panel`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`setError()`	Records an exception thrown during capture or hydration so `LogTarget` can surface it in the UI.	`Panel`
`setRenderContext()`	Installs the framework-neutral render context prepared for this panel by the debugger action.	`Panel`
`trigger()`	Triggers an event.	`yii\base\Component`
`getToolbarItems()` protected	Returns the structured items rendered on the debug toolbar for this panel.	`Panel`

Property details

$actions

public array<string, array<string, mixed>|class-string> $actions = []

Standalone actions merged into the debug module’s Module::$actionMap, keyed by action ID.

Class-string entries are instantiated with no constructor arguments and receive typed dependencies, including the owning panel, through run() parameter injection.

Method details

capture()

public function capture(): PHPForge\Debug\Storage\PanelSnapshot|null

Captures the panel payload for the current request.

Invoked by LogTarget::export() at request end; the DTO is encoded into the request’s versioned JSON snapshot and rehydrated through hydrate() on read-back.

Returns

PHPForge\Debug\Storage\PanelSnapshot|null: Typed payload to persist; null when the panel records nothing.

getDetail()

public function getDetail(): string

Returns the detail view markup rendered when the user opens the panel.

Returns

string: Detail view markup; '' when the panel does not expose a detail view.

getError()

public function getError(): PHPForge\Debug\Storage\ExceptionSnapshot|null

Returns the exception captured while collecting the panel payload, if any.

Returns

PHPForge\Debug\Storage\ExceptionSnapshot|null: Captured failure, or null when the panel ran cleanly.

getName()

public function getName(): string

Returns the panel display name shown on the toolbar and the detail navigation.

Returns

string: Display name; '' for the base class.

getRenderContext()

public function getRenderContext(): PHPForge\Debug\Panel\PanelRenderContext|null

Returns the framework-neutral render context for the active debugger request, when one has been prepared.

Returns

PHPForge\Debug\Panel\PanelRenderContext|null: Prepared render context, or null outside a debugger request.

getToolbarData()

public function getToolbarData(): array<string, mixed>

Returns the toolbar envelope wrapping the panel’s icon, items, and URL.

Renders the error envelope when getError() is non-null; otherwise wraps the structured items from getToolbarItems(). Panels that yield no items are skipped. A panel whose only item links elsewhere points the envelope url at that item, so the chip label and its badge open the same capture.

Returns

array<string, mixed>: Toolbar envelope; [] to skip the panel.

getToolbarIcon()

public function getToolbarIcon(): string|null

Returns the icon key used on the panel’s toolbar chip, or null to render no icon.

The key is matched against the SVG library shipped by php-forge/debug-core and rendered as a CSS-mask glyph that takes its color from the surrounding chip text.

Returns

string|null: Icon key, or null to render no icon.

getTraceLine()

public function getTraceLine(array<string, mixed> $options): string

Builds a trace line for the toolbar through the shared Trace renderer, applying Module::$tracePathMappings and the configured Module::$traceLine template (or callable).

A missing module, null, false, and any value outside the documented contract render escaped plain text; a string always becomes the placeholder template, never a function name; any other callable keeps receiving the frame and the panel, so the documented ($options, $panel) contract survives the delegation.

The renderer escapes every substituted value, and falls back to an escaped dump when file or line is missing internal PHP functions such as call_user_func() may produce frames without those keys, see https://www.php.net/manual/en/function.debug-backtrace.php#59713.

Parameters

Parameter	Type	Description
`$options`	`array<string, mixed>`	Trace frame; consumes `file`, `line`, and optional `text`.

Returns

string: Trace line ready for inclusion on the toolbar.

getUrl()

public function getUrl(array<string, mixed>|null $additionalParams = null): string

Returns the URL pointing to this panel’s detail view for the current request tag.

Parameters

Parameter	Type	Description
`$additionalParams`	`array<string, mixed>\|null`	Extra query parameters merged into the route.

Returns

string: Absolute URL to the panel detail view.

getViewPath()

public function getViewPath(): string

Returns the directory under which the panel’s relative views resolve.

Returns

string: Directory the panel views resolve against.

hasContent()

public function hasContent(): bool

Returns whether the panel captured content for the loaded request.

The sidebar nav skips panels that report false for the active capture, so integration panels can activate per request — the way the AJAX flag only surfaces on XHR captures. Returns true by default, keeping every core panel listed on every capture.

Returns

bool: true when the panel has content for the loaded capture; false otherwise.

hasError()

public function hasError(): bool

Returns true when setError() captured an exception during panel capture or hydration.

Returns

bool: true when a failure was captured; false otherwise.

hydrate()

public function hydrate(array<string, mixed> $payload): void

Hydrates the panel from the JSON payload previously produced by capture().

Invoked by LogTarget::loadTagToPanels() when the user opens a captured request.

Parameters

Parameter	Type	Description
`$payload`	`array<string, mixed>`	Captured panel payload.

Throws

PHPForge\Debug\Storage\HydrationException: when the payload is invalid or cannot be applied to the panel.

isEnabled()

public function isEnabled(): bool

Indicates whether this panel is enabled and should be registered by the module.

Returns

bool: true when the module should register the panel; false otherwise.

isVisible()

public function isVisible(): bool

Returns whether the panel should appear in the toolbar and sidebar navigation.

Visibility is independent from hasContent() and does not disable capture, hydration, or direct detail URLs. This lets compatibility panels keep collecting data without competing with a panel that presents the same diagnostics.

Returns

bool: true when the panel appears in the toolbar and sidebar; false otherwise.

moduleBound()

public function moduleBound(): void

Completes module-dependent wiring after the container module binds $id and $module.

Invoked once by Module for every registered panel, whether configured as a class name, a configuration array, or an already-instantiated Panel. Override this hook for setup that requires the owning module; for a prebuilt instance, BaseObject::init() executes before the module reference is bound.

setError()

public function setError(PHPForge\Debug\Storage\ExceptionSnapshot $error): void

Records an exception thrown during capture or hydration so LogTarget can surface it in the UI.

Parameters

Parameter	Type	Description
`$error`	`PHPForge\Debug\Storage\ExceptionSnapshot`	Failure captured for this panel.

setRenderContext()

public function setRenderContext(PHPForge\Debug\Panel\PanelRenderContext|null $renderContext): void

Installs the framework-neutral render context prepared for this panel by the debugger action.

Parameters

Parameter	Type	Description
`$renderContext`	`PHPForge\Debug\Panel\PanelRenderContext\|null`	Render context, or `null` to clear it.

getToolbarItems()

protected function getToolbarItems(): array<int, array<string, mixed>>

Returns the structured items rendered on the debug toolbar for this panel.

Subclasses override this instead of getToolbarData(), which handles the error envelope and the title/url/items wrapping.

Return value semantics:

a non-empty list of item descriptors: rendered as structured metrics on the toolbar,
[] (the default): the panel renders no toolbar chip.

Returns

array<int, array<string, mixed>>: Structured items; [] to skip the panel.