# DbCollector

> Retains completed database observations only within the current debugger request lifecycle.

[API reference](/docs/api/index.md) › [Yii3 Debug](/docs/extensions/yii3-debug/reference/index.md) › [Collector](/docs/extensions/yii3-debug/reference/collector/index.md) › DbCollector

| final class | `Yii3\Debug\Collector\DbCollector` |
| --- | --- |
| Implements | [`CollectorInterface`](https://github.com/php-forge/debug/blob/e4fbb8c3238a4d011ceef5e0094344abd50deaf4/src/CollectorInterface.php) |
| Source | [`src/Collector/DbCollector.php`](https://github.com/yii3/debug/blob/main/src/Collector/DbCollector.php#L17) |

Retains completed database observations only within the current debugger request lifecycle.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`begin()`](#method-begin) | Opens a block for one statement. | `DbCollector` |
| [`capture()`](#method-capture) | Encodes the captured statements into the Database panel payload. | `DbCollector` |
| [`end()`](#method-end) | Closes the block opened for the same token and records the completed statement. | `DbCollector` |
| [`id()`](#method-id) | Returns the stable identifier of this collector. | `DbCollector` |
| [`isStarted()`](#method-isStarted) | Returns whether the collector is capturing for the current request. | `DbCollector` |
| [`observe()`](#method-observe) | Records a statement already assembled elsewhere. | `DbCollector` |
| [`reportFailure()`](#method-reportFailure) | Records an instrumentation failure, so a broken profiler surfaces in the panel instead of silently dropping data. | `DbCollector` |
| [`reportRows()`](#method-reportRows) | Records the row count reported by the statement that is about to complete. | `DbCollector` |
| [`shutdown()`](#method-shutdown) | Stops capturing and clears the statements accumulated for the request. | `DbCollector` |
| [`startup()`](#method-startup) | Starts capturing, discarding anything left from a previous request. | `DbCollector` |

## Method details

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

```php
public function begin(string $token, float $time, list<array<string, mixed>> $trace): void
```

Opens a block for one statement.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$token` | `string` | Statement text identifying the block. |
| `$time` | `float` | Start timestamp, in seconds. |
| `$trace` | `list<array<string, mixed>>` | Backtrace frames of the call site. |

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

```php
public function capture(): array<string, mixed>|null
```

Encodes the captured statements into the Database panel payload.

**Returns**

`array<string, mixed>|null`: Encoded Db panel payload; `null` when the collector never started.

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

```php
public function end(string $token, float $time): void
```

Closes the block opened for the same token and records the completed statement.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$token` | `string` | Statement text identifying the block. |
| `$time` | `float` | Completion timestamp, in seconds. |

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

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

Returns the stable identifier of this collector.

**Returns**

`string`: Stable ID pairing this collector with its panel.

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

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

Returns whether the collector is capturing for the current request.

**Returns**

`bool`: `true` while the collector is capturing; `false` otherwise.

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

```php
public function observe(PHPForge\Debug\Panel\Db\QueryRow $row): void
```

Records a statement already assembled elsewhere.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$row` | `PHPForge\Debug\Panel\Db\QueryRow` | Statement to append to the capture. |

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

```php
public function reportFailure(Throwable $failure): void
```

Records an instrumentation failure, so a broken profiler surfaces in the panel instead of silently
dropping data.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$failure` | [`Throwable`](https://www.php.net/manual/en/class.throwable.php) | Failure raised while instrumenting the connection. |

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

```php
public function reportRows(int|null $rows): void
```

Records the row count reported by the statement that is about to complete.

The last report before [`end()`](/docs/extensions/yii3-debug/reference/collector/dbcollector/index.md#method-end) wins, so a retry handler re-executing the same statement overrides the count
of the failed attempt.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$rows` | `int\|null` | Rows returned or affected, or `null` when the statement did not complete. |

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

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

Stops capturing and clears the statements accumulated for the request.

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

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

Starts capturing, discarding anything left from a previous request.