# Panel

> Base class for debug toolbar panels.

[API reference](/docs/api/index.md) › [Debug](/docs/extensions/debug/reference/index.md) › Panel

| class | `yii\debug\Panel` |
| --- | --- |
| Extends | [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\ViewContextInterface`](/docs/api/yii/base/viewcontextinterface/index.md), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Source | [`src/Panel.php`](https://github.com/yii2-extensions/debug/blob/main/src/Panel.php#L26) |

14 subclasses:

- [`yii\debug\panels\AssetPanel`](/docs/extensions/debug/reference/panels/assetpanel/index.md)
- [`yii\debug\panels\ConfigPanel`](/docs/extensions/debug/reference/panels/configpanel/index.md)
- [`yii\debug\panels\DbPanel`](/docs/extensions/debug/reference/panels/dbpanel/index.md)
- [`yii\debug\panels\DumpPanel`](/docs/extensions/debug/reference/panels/dumppanel/index.md)
- [`yii\debug\panels\EventPanel`](/docs/extensions/debug/reference/panels/eventpanel/index.md)
- [`yii\debug\panels\JsonPanel`](/docs/extensions/debug/reference/panels/jsonpanel/index.md)
- [`yii\debug\panels\LogPanel`](/docs/extensions/debug/reference/panels/logpanel/index.md)
- [`yii\debug\panels\MailPanel`](/docs/extensions/debug/reference/panels/mailpanel/index.md)
- [`yii\debug\panels\ProfilingPanel`](/docs/extensions/debug/reference/panels/profilingpanel/index.md)
- [`yii\debug\panels\ProviderPanel`](/docs/extensions/debug/reference/panels/providerpanel/index.md)
- [`yii\debug\panels\QueuePanel`](/docs/extensions/debug/reference/panels/queuepanel/index.md)
- [`yii\debug\panels\RequestPanel`](/docs/extensions/debug/reference/panels/requestpanel/index.md)
- [`yii\debug\panels\RouterPanel`](/docs/extensions/debug/reference/panels/routerpanel/index.md)
- [`yii\debug\panels\UserPanel`](/docs/extensions/debug/reference/panels/userpanel/index.md)

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`](/docs/extensions/debug/reference/module/index.md) wires [`$id`](/docs/extensions/debug/reference/panel/index.md#property-id), [`$module`](/docs/extensions/debug/reference/panel/index.md#property-module), and [`$tag`](/docs/extensions/debug/reference/panel/index.md#property-tag) automatically on
registration.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$actions`](#property-actions) | `array<string, array<string, mixed>\|class-string>` | Standalone actions merged into the debug module's [`Module::$actionMap`](/docs/api/yii/base/module/index.md#property-actionMap), keyed by action ID. Default: `[]`. | `Panel` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-detail"></span>`$detail` read-only | `string` | Detail view markup; `''` when the panel does not expose a detail view. | `Panel` |
| <span id="property-id"></span>`$id` | `string` | Panel unique identifier, assigned by the container module on registration. Default: `''`. | `Panel` |
| <span id="property-module"></span>`$module` | [`Module`](/docs/extensions/debug/reference/module/index.md)`\|null` | Debug module owning this panel. Default: `null`. | `Panel` |
| <span id="property-name"></span>`$name` read-only | `string` | Display name; `''` for the base class. | `Panel` |
| <span id="property-renderContext"></span>`$renderContext` | `PHPForge\Debug\Panel\PanelRenderContext\|null` | Prepared render context, or `null` outside a debugger request. | `Panel` |
| <span id="property-tag"></span>`$tag` | `string` | Tag of the request whose data this panel currently exposes. Default: `''`. | `Panel` |
| <span id="property-toolbarData"></span>`$toolbarData` read-only | `array<string, mixed>` | Toolbar envelope; `[]` to skip the panel. | `Panel` |
| <span id="property-toolbarIcon"></span>`$toolbarIcon` read-only | `string\|null` | Icon key, or `null` to render no icon. | `Panel` |
| <span id="property-url"></span>`$url` read-only | `string` | Absolute URL to the panel detail view. | `Panel` |
| <span id="property-viewPath"></span>`$viewPath` read-only | `string` | Directory the panel views resolve against. | `Panel` |
| <span id="property-error"></span>`$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 |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`capture()`](#method-capture) | Captures the panel payload for the current request. | `Panel` |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`getDetail()`](#method-getDetail) | Returns the detail view markup rendered when the user opens the panel. | `Panel` |
| [`getError()`](#method-getError) | Returns the exception captured while collecting the panel payload, if any. | `Panel` |
| [`getName()`](#method-getName) | Returns the panel display name shown on the toolbar and the detail navigation. | `Panel` |
| [`getRenderContext()`](#method-getRenderContext) | Returns the framework-neutral render context for the active debugger request, when one has been prepared. | `Panel` |
| [`getToolbarData()`](#method-getToolbarData) | Returns the toolbar envelope wrapping the panel's icon, items, and URL. | `Panel` |
| [`getToolbarIcon()`](#method-getToolbarIcon) | Returns the icon key used on the panel's toolbar chip, or `null` to render no icon. | `Panel` |
| [`getTraceLine()`](#method-getTraceLine) | Builds a trace line for the toolbar through the shared [`Trace`](https://github.com/php-forge/debug-core/blob/b70459f033a1d7a1c5edf7951029aad2061986dd/src/Helper/Trace.php) renderer, applying [`Module::$tracePathMappings`](/docs/extensions/debug/reference/module/index.md#property-tracePathMappings) and the configured [`Module::$traceLine`](/docs/extensions/debug/reference/module/index.md#property-traceLine) template (or callable). | `Panel` |
| [`getUrl()`](#method-getUrl) | Returns the URL pointing to this panel's detail view for the current request tag. | `Panel` |
| [`getViewPath()`](#method-getViewPath) | Returns the directory under which the panel's relative views resolve. | `Panel` |
| [`hasContent()`](#method-hasContent) | Returns whether the panel captured content for the loaded request. | `Panel` |
| [`hasError()`](#method-hasError) | Returns `true` when [`setError()`](/docs/extensions/debug/reference/panel/index.md#method-setError) captured an exception during panel capture or hydration. | `Panel` |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`hydrate()`](#method-hydrate) | Hydrates the panel from the JSON payload previously produced by [`capture()`](/docs/extensions/debug/reference/panel/index.md#method-capture). | `Panel` |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`isEnabled()`](#method-isEnabled) | Indicates whether this panel is enabled and should be registered by the module. | `Panel` |
| [`isVisible()`](#method-isVisible) | Returns whether the panel should appear in the toolbar and sidebar navigation. | `Panel` |
| [`moduleBound()`](#method-moduleBound) | Completes module-dependent wiring after the container module binds [`$id`](/docs/extensions/debug/reference/panel/index.md#property-id) and [`$module`](/docs/extensions/debug/reference/panel/index.md#property-module). | `Panel` |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`setError()`](#method-setError) | Records an exception thrown during capture or hydration so [`LogTarget`](/docs/extensions/debug/reference/logtarget/index.md) can surface it in the UI. | `Panel` |
| [`setRenderContext()`](#method-setRenderContext) | Installs the framework-neutral render context prepared for this panel by the debugger action. | `Panel` |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`getToolbarItems()`](#method-getToolbarItems) protected | Returns the structured items rendered on the debug toolbar for this panel. | `Panel` |

## Property details

### $actions <span id="property-actions"></span>

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

Standalone actions merged into the debug module's [`Module::$actionMap`](/docs/api/yii/base/module/index.md#property-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() <span id="method-capture"></span>

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

Captures the panel payload for the current request.

Invoked by [`LogTarget::export()`](/docs/extensions/debug/reference/logtarget/index.md#method-export) at request end; the DTO is encoded into the request's versioned JSON
snapshot and rehydrated through [`hydrate()`](/docs/extensions/debug/reference/panel/index.md#method-hydrate) on read-back.

**Returns**

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

### getDetail() <span id="method-getDetail"></span>

```php
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() <span id="method-getError"></span>

```php
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() <span id="method-getName"></span>

```php
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() <span id="method-getRenderContext"></span>

```php
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() <span id="method-getToolbarData"></span>

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

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

Renders the error envelope when [`getError()`](/docs/extensions/debug/reference/panel/index.md#method-getError) is non-`null`; otherwise wraps the structured items from
[`getToolbarItems()`](/docs/extensions/debug/reference/panel/index.md#method-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() <span id="method-getToolbarIcon"></span>

```php
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() <span id="method-getTraceLine"></span>

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

Builds a trace line for the toolbar through the shared [`Trace`](https://github.com/php-forge/debug-core/blob/b70459f033a1d7a1c5edf7951029aad2061986dd/src/Helper/Trace.php) renderer, applying
[`Module::$tracePathMappings`](/docs/extensions/debug/reference/module/index.md#property-tracePathMappings) and the configured [`Module::$traceLine`](/docs/extensions/debug/reference/module/index.md#property-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()`](https://www.php.net/manual/en/function.call-user-func.php) may produce frames without those keys, see
[`https://www.php.net/manual/en/function.debug-backtrace.php#59713`](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() <span id="method-getUrl"></span>

```php
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() <span id="method-getViewPath"></span>

```php
public function getViewPath(): string
```

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

**Returns**

`string`: Directory the panel views resolve against.

### hasContent() <span id="method-hasContent"></span>

```php
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() <span id="method-hasError"></span>

```php
public function hasError(): bool
```

Returns `true` when [`setError()`](/docs/extensions/debug/reference/panel/index.md#method-setError) captured an exception during panel capture or hydration.

**Returns**

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

### hydrate() <span id="method-hydrate"></span>

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

Hydrates the panel from the JSON payload previously produced by [`capture()`](/docs/extensions/debug/reference/panel/index.md#method-capture).

Invoked by [`LogTarget::loadTagToPanels()`](/docs/extensions/debug/reference/logtarget/index.md#method-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() <span id="method-isEnabled"></span>

```php
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() <span id="method-isVisible"></span>

```php
public function isVisible(): bool
```

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

Visibility is independent from [`hasContent()`](/docs/extensions/debug/reference/panel/index.md#method-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() <span id="method-moduleBound"></span>

```php
public function moduleBound(): void
```

Completes module-dependent wiring after the container module binds [`$id`](/docs/extensions/debug/reference/panel/index.md#property-id) and [`$module`](/docs/extensions/debug/reference/panel/index.md#property-module).

Invoked once by [`Module`](/docs/extensions/debug/reference/module/index.md) for every registered panel, whether configured as a class name, a configuration
array, or an already-instantiated [`Panel`](/docs/extensions/debug/reference/panel/index.md). Override this hook for setup that requires the owning module;
for a prebuilt instance, [`BaseObject::init()`](/docs/api/yii/base/baseobject/index.md#method-init) executes before the module reference is bound.

### setError() <span id="method-setError"></span>

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

Records an exception thrown during capture or hydration so [`LogTarget`](/docs/extensions/debug/reference/logtarget/index.md) can surface it in the UI.

**Parameters**

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

### setRenderContext() <span id="method-setRenderContext"></span>

```php
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() <span id="method-getToolbarItems"></span>

```php
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()`](/docs/extensions/debug/reference/panel/index.md#method-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.