# MailCollector

> Captures every message yiisoft/mailer sends during the request for the Mail panel.

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

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

Captures every message `yiisoft/mailer` sends during the request for the Mail panel.

Each message is recorded in the capture shape the Yii2 collector produces, so a capture written by either host
renders through the same [`MailPanel`](https://github.com/php-forge/debug-core/blob/b70459f033a1d7a1c5edf7951029aad2061986dd/src/Panel/Mail/MailPanel.php), and is stored as an `.eml` file through
[`MailFileStore`](/docs/extensions/yii3-debug/reference/mail/mailfilestore/index.md). `yiisoft/mailer` dispatches [`AfterSend`](https://github.com/yiisoft/mailer/blob/8c0ba1558760ce990285ce7f24b91f6fb619b06f/src/Event/AfterSend.php) only once the transport accepted the message, so
every captured message is reported as sent.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Creates a mail collector that stores message files and reports conversion failures. | `MailCollector` |
| [`capture()`](#method-capture) | Encodes the captured messages into the Mail panel payload. | `MailCollector` |
| [`collect()`](#method-collect) | Records a message the mailer sent and stores it as an `.eml` file. | `MailCollector` |
| [`id()`](#method-id) | Returns the stable identifier of this collector. | `MailCollector` |
| [`mailFiles()`](#method-mailFiles) | Returns the names of the `.eml` files stored for the captured messages. | `MailCollector` |
| [`reconcileFiles()`](#method-reconcileFiles) | Deletes aged `.eml` files no retained capture refers to. | `MailCollector` |
| [`removeFiles()`](#method-removeFiles) | Deletes the `.eml` files of a capture that was evicted from history or never committed. | `MailCollector` |
| [`shutdown()`](#method-shutdown) | Stops capturing and clears the messages accumulated for the request. | `MailCollector` |
| [`startup()`](#method-startup) | Starts capturing, discarding anything left from a previous request. | `MailCollector` |

## Method details

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

```php
public function __construct(Yii3\Debug\Mail\MailFileStore $files, Closure(Yiisoft\Mailer\MessageInterface): Symfony\Component\Mime\Email|null $emailFactory = null, Psr\Log\LoggerInterface|null $logger = null)
```

Creates a mail collector that stores message files and reports conversion failures.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$files` | [`Yii3\Debug\Mail\MailFileStore`](/docs/extensions/yii3-debug/reference/mail/mailfilestore/index.md) | Store the `.eml` files are written to and removed from. |
| `$emailFactory` | [`Closure`](https://www.php.net/manual/en/class.closure.php)`(Yiisoft\Mailer\MessageInterface): Symfony\Component\Mime\Email\|null` | Converter building the Symfony email the `yiisoft/mailer-symfony` adapter sends, or `null` when the adapter is not installed and the message accessors are read instead. |
| `$logger` | `Psr\Log\LoggerInterface\|null` | Logger receiving a warning when the conversion fails, or `null` to fall back to the message accessors without reporting it. |

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

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

Encodes the captured messages into the Mail panel payload.

**Returns**

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

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

```php
public function collect(Yiisoft\Mailer\Event\AfterSend $event): void
```

Records a message the mailer sent and stores it as an `.eml` file.

With the Symfony email the body, charset, headers, time, and file are read exactly as the Yii2 collector reads
them from its Symfony message; without it they come from the message accessors. The file holds the RFC 5322
source, or the message string representation when there is no Symfony email or Symfony refuses to serialize one
that lacks a sender or recipient.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$event` | [`AfterSend`](https://github.com/yiisoft/mailer/blob/8c0ba1558760ce990285ce7f24b91f6fb619b06f/src/Event/AfterSend.php) | Event the mailer dispatched after the transport accepted the message. |

### 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.

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

```php
public function mailFiles(): list<string>
```

Returns the names of the `.eml` files stored for the captured messages.

The request summary records them, so evicting the capture from history also removes its files.

**Returns**

`list<string>`: File names in send order; messages whose file could not be written are skipped.

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

```php
public function reconcileFiles(iterable<string> $referencedFiles): void
```

Deletes aged `.eml` files no retained capture refers to.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$referencedFiles` | `iterable<string>` | File names referenced by the committed manifest. |

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

```php
public function removeFiles(iterable<string> $files): void
```

Deletes the `.eml` files of a capture that was evicted from history or never committed.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$files` | `iterable<string>` | File names recorded by the capture. |

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

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

Stops capturing and clears the messages accumulated for the request.

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

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

Starts capturing, discarding anything left from a previous request.