# Collector

> Base class for the Yii2 debug collectors.

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

| abstract class | `yii\debug\collectors\Collector` |
| --- | --- |
| Implements | [`CollectorInterface`](https://github.com/php-forge/debug/blob/e4fbb8c3238a4d011ceef5e0094344abd50deaf4/src/CollectorInterface.php) |
| Source | [`src/collectors/Collector.php`](https://github.com/yii2-extensions/debug/blob/main/src/collectors/Collector.php#L29) |

12 subclasses:

- [`AssetCollector`](/docs/extensions/debug/reference/collectors/assetcollector/index.md)
- [`ConfigCollector`](/docs/extensions/debug/reference/collectors/configcollector/index.md)
- [`DbCollector`](/docs/extensions/debug/reference/collectors/dbcollector/index.md)
- [`DumpCollector`](/docs/extensions/debug/reference/collectors/dumpcollector/index.md)
- [`EventCollector`](/docs/extensions/debug/reference/collectors/eventcollector/index.md)
- [`LogCollector`](/docs/extensions/debug/reference/collectors/logcollector/index.md)
- [`MailCollector`](/docs/extensions/debug/reference/collectors/mailcollector/index.md)
- [`ProfilingCollector`](/docs/extensions/debug/reference/collectors/profilingcollector/index.md)
- [`QueueCollector`](/docs/extensions/debug/reference/collectors/queuecollector/index.md)
- [`RequestCollector`](/docs/extensions/debug/reference/collectors/requestcollector/index.md)
- [`RouterCollector`](/docs/extensions/debug/reference/collectors/routercollector/index.md)
- [`UserCollector`](/docs/extensions/debug/reference/collectors/usercollector/index.md)

Base class for the Yii2 debug collectors.

Owns the idempotent startup/shutdown lifecycle, the debug-module context, and the single encoding step that turns
the typed snapshot returned by [`snapshot()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-snapshot) into the persisted payload; subclasses hook event subscription into
[`start()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-start) / [`stop()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-stop) and read accumulated log messages through [`getLogMessages()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-getLogMessages).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-module"></span>`$module` | [`yii\debug\Module`](/docs/extensions/debug/reference/module/index.md)`\|null` | Debug module supplying the log target and sibling collectors, assigned by the module on registration. Default: `null`. | `Collector` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`capture()`](#method-capture) final | Encodes the typed snapshot built by the subclass into the payload persisted for the panel. | `Collector` |
| [`instrument()`](#method-instrument) | Installs low-level instrumentation as soon as the module registers the collector, before the panels are built. | `Collector` |
| [`shutdown()`](#method-shutdown) final | Deactivates the collector once, releasing any subscription created by [`start()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-start). | `Collector` |
| [`startup()`](#method-startup) final | Activates the collector once at the start of the request lifecycle. | `Collector` |
| [`getLogMessages()`](#method-getLogMessages) protected | Returns the accumulated log messages, optionally filtered by level, category, and exclusion lists. | `Collector` |
| [`getLogTarget()`](#method-getLogTarget) protected | Returns the initialized log target of the owning debug module. | `Collector` |
| [`isStarted()`](#method-isStarted) protected | Returns whether the collector is active for the current request. | `Collector` |
| [`snapshot()`](#method-snapshot) protected abstract | Builds the typed snapshot for the current request. | `Collector` |
| [`start()`](#method-start) protected | Hook invoked once when the collector activates; subclasses subscribe to framework events here. | `Collector` |
| [`stop()`](#method-stop) protected | Hook invoked once when the collector deactivates; subclasses detach subscriptions and clear state here. | `Collector` |

## Method details

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

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

Encodes the typed snapshot built by the subclass into the payload persisted for the panel.

**Returns**

`array<string, mixed>|null`: Encoded panel payload; `null` when the collector recorded nothing.

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

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

Installs low-level instrumentation as soon as the module registers the collector, before the panels are built.

[`Module::initCollectors()`](/docs/extensions/debug/reference/module/index.md#method-initCollectors) calls this hook while the debugger is still bootstrapping, so a subclass whose
data would otherwise miss the debugger's own bootstrap work (queries issued by a panel constructor, for
instance) can hook the framework here instead of waiting for [`start()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-start). Implementations must be idempotent
and must not depend on the log target, which is wired later.

The default implementation does nothing.

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

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

Deactivates the collector once, releasing any subscription created by [`start()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-start).

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

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

Activates the collector once at the start of the request lifecycle.

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

```php
protected function getLogMessages(int $levels = 0, list<string> $categories = [], list<string> $except = [], Closure(mixed): string|null $formatter = null): list<yii\debug\collectors\LogTuple>
```

Returns the accumulated log messages, optionally filtered by level, category, and exclusion lists.

A [`PsrMessage`](/docs/api/yii/log/psrmessage/index.md) payload also yields its PSR-3 context at tuple index `6`, normalized and redacted through the
module capture policy. A `category` value identical to the tuple category is dropped because it already names the
row, as [`PsrLogger`](/docs/api/yii/log/psrlogger/index.md) copies it there; any other `category` value stays in the context. Every other
payload yields `[]`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$levels` | `int` | Bitmask of `yii\log\Logger::LEVEL_*` values; `0` keeps every level. |
| `$categories` | `list<string>` | Category patterns to include; empty keeps every category. |
| `$except` | `list<string>` | Category patterns to exclude. |
| `$formatter` | [`Closure`](https://www.php.net/manual/en/class.closure.php)`(mixed): string\|null` | Custom payload formatter; defaults to a readable string export. |

**Returns**

`list<yii\debug\collectors\LogTuple>`: Canonical string-based log messages in capture order.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): when the debug module log target is not initialized.

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

```php
protected function getLogTarget(): yii\debug\LogTarget
```

Returns the initialized log target of the owning debug module.

**Returns**

[`yii\debug\LogTarget`](/docs/extensions/debug/reference/logtarget/index.md): Initialized log target.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): when the debug module log target is not initialized.

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

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

Returns whether the collector is active for the current request.

**Returns**

`bool`: `true` while the collector is active for the request; `false` otherwise.

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

```php
abstract protected function snapshot(): PHPForge\Debug\Storage\PanelSnapshot|null
```

Builds the typed snapshot for the current request.

**Returns**

`PHPForge\Debug\Storage\PanelSnapshot|null`: Typed payload, or `null` when the collector recorded nothing.

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

```php
protected function start(): void
```

Hook invoked once when the collector activates; subclasses subscribe to framework events here.

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

```php
protected function stop(): void
```

Hook invoked once when the collector deactivates; subclasses detach subscriptions and clear state here.