# ToolbarDataMapper

> Maps Yii2 panel envelopes to the shared typed toolbar contract.

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

| final readonly class | `yii\debug\ToolbarDataMapper` |
| --- | --- |
| Source | [`src/ToolbarDataMapper.php`](https://github.com/yii2-extensions/debug/blob/main/src/ToolbarDataMapper.php#L20) |

Maps Yii2 panel envelopes to the shared typed toolbar contract.

Start from [`create()`](/docs/extensions/debug/reference/toolbardatamapper/index.md#method-create) with the values the toolbar cannot render without, then layer the optional chrome through
the immutable `with*()` methods, which mirror [`ToolbarData`](https://github.com/php-forge/debug-core/blob/b70459f033a1d7a1c5edf7951029aad2061986dd/src/Toolbar/ToolbarData.php). [`map()`](/docs/extensions/debug/reference/toolbardatamapper/index.md#method-map) closes the chain.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`create()`](#method-create) static | Creates a mapper for a capture, ready for immutable enrichment. | `ToolbarDataMapper` |
| [`map()`](#method-map) | Creates the JSON-ready toolbar payload. | `ToolbarDataMapper` |
| [`withBranding()`](#method-withBranding) | Returns a copy carrying the brand assets and the version labels. | `ToolbarDataMapper` |
| [`withNavigation()`](#method-withNavigation) | Returns a copy carrying the debugger navigation URLs. | `ToolbarDataMapper` |
| [`withPresentation()`](#method-withPresentation) | Returns a copy carrying the drawer presentation settings. | `ToolbarDataMapper` |

## Method details

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

```php
public static function create(string $tag, string $title): self
```

Creates a mapper for a capture, ready for immutable enrichment.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$tag` | `string` | Tag of the capture the toolbar links to. |
| `$title` | `string` | Title of the captured request. |

**Returns**

`self`: Mapper carrying only the mandatory toolbar identity.

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

```php
public function map(array<string, yii\debug\Panel> $panels): array{configUrl: string, defaultHeight: int, iconBaseUrl: string, indexUrl: string, items: list<array<string, mixed>>, logo: string|null, logoFallback: string|null, phpInfoUrl: string|null, phpVersion: string|null, position: string, tag: string, title: string, yiiVersion: string|null}
```

Creates the JSON-ready toolbar payload.

Every panel is serialized through the Debug Core DTOs, so fields outside the `id`, `title`, `url`, `icon`, and
`items` schema are dropped. A panel whose envelope breaks that schema renders a single error chip carrying
[`Message::TOOLBAR_ENVELOPE_INVALID`](/docs/extensions/debug/reference/exception/message/index.md#case-TOOLBAR_ENVELOPE_INVALID) as its tooltip, keeping the failure contained to its own chip.

Chips are emitted in the order the module registered the panels, which the shared registration policy already
resolved, so the toolbar mirrors the sidebar grouping. Every panel the module registry classifies as an extension,
and every panel it does not list (a raw JSON fallback), carries `extension: true`, so the shared toolbar groups it
under its Extensions menu; built-in panels omit the key and stay inline.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$panels` | `array<string,` [`Panel`](/docs/extensions/debug/reference/panel/index.md)`>` | Registered Yii2 panels keyed by ID, in display order. |

**Returns**

`array{configUrl: string, defaultHeight: int, iconBaseUrl: string, indexUrl: string, items: list<array<string, mixed>>, logo: string|null, logoFallback: string|null, phpInfoUrl: string|null, phpVersion: string|null, position: string, tag: string, title: string, yiiVersion: string|null}`: Payload consumed by the shared toolbar runtime.

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

```php
public function withBranding(string|null $logo, string|null $logoFallback = null, string|null $phpVersion = null, string|null $yiiVersion = null): self
```

Returns a copy carrying the brand assets and the version labels.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$logo` | `string\|null` | Logo as a data URI, or `null` to fall back. |
| `$logoFallback` | `string\|null` | Logo used when the primary one is unavailable, or `null` for none. |
| `$phpVersion` | `string\|null` | PHP version label, or `null` when unavailable. |
| `$yiiVersion` | `string\|null` | Yii version label, or `null` when unavailable. |

**Returns**

`self`: Mapper with the branding applied.

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

```php
public function withNavigation(string $indexUrl, string|null $configUrl = null, string|null $phpInfoUrl = null): self
```

Returns a copy carrying the debugger navigation URLs.

An omitted configuration URL falls back to the history URL, which Debug Core requires to be non-`null`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$indexUrl` | `string` | URL of the history page. |
| `$configUrl` | `string\|null` | URL of the configuration panel, or `null` to reuse the history URL. |
| `$phpInfoUrl` | `string\|null` | URL of the `phpinfo()` page, or `null` when disabled. |

**Returns**

`self`: Mapper with the navigation applied.

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

```php
public function withPresentation(string $position, int $defaultHeight, string $iconBaseUrl = ''): self
```

Returns a copy carrying the drawer presentation settings.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$position` | `string` | Edge the toolbar docks to. |
| `$defaultHeight` | `int` | Collapsed toolbar height, in pixels. |
| `$iconBaseUrl` | `string` | Base URL the panel icons resolve against. |

**Returns**

`self`: Mapper with the presentation applied.