# MailFileStore

> Stores the .eml files of captured mail messages and removes them once no retained capture refers to them.

[API reference](/docs/api/index.md) › [Yii3 Debug](/docs/extensions/yii3-debug/reference/index.md) › [Mail](/docs/extensions/yii3-debug/reference/mail/index.md) › MailFileStore

| final readonly class | `Yii3\Debug\Mail\MailFileStore` |
| --- | --- |
| Source | [`src/Mail/MailFileStore.php`](https://github.com/yii3/debug/blob/main/src/Mail/MailFileStore.php#L35) |

Stores the `.eml` files of captured mail messages and removes them once no retained capture refers to them.

Only bare file names are resolved, so a name read back from a manifest or a request cannot reach outside the mail
directory.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`__construct()`](#method-__construct) | Creates a mail-file store with its directory, permissions, and optional failure logger. | `MailFileStore` |
| [`reconcile()`](#method-reconcile) | Deletes aged `.eml` files no retained capture refers to. | `MailFileStore` |
| [`remove()`](#method-remove) | Deletes the `.eml` files of a capture that was evicted from history or never committed. | `MailFileStore` |
| [`resolve()`](#method-resolve) | Returns the absolute path of a stored `.eml` file. | `MailFileStore` |
| [`write()`](#method-write) | Writes one message to the mail directory under a new unique name. | `MailFileStore` |

## Method details

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

```php
public function __construct(string $path, int $dirMode = 0700, int|null $fileMode = 0600, Psr\Log\LoggerInterface|null $logger = null)
```

Creates a mail-file store with its directory, permissions, and optional failure logger.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$path` | `string` | Directory holding the `.eml` files, already resolved from any alias. |
| `$dirMode` | `int` | Permission bits applied to the directory when it is created. |
| `$fileMode` | `int\|null` | Permission bits applied to every written file, or `null` to keep the process umask. |
| `$logger` | `Psr\Log\LoggerInterface\|null` | Logger receiving a warning when a file cannot be written, or `null` to report the failure only through the empty file name. |

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

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

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

The grace period keeps a file written by a concurrent request whose capture is not committed yet. A file that
cannot be deleted stays for the next reconciliation.

**Parameters**

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

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

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

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

Unsafe or unknown names are skipped. A file that cannot be deleted is left for [`reconcile()`](/docs/extensions/yii3-debug/reference/mail/mailfilestore/index.md#method-reconcile).

**Parameters**

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

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

```php
public function resolve(string $file): string|null
```

Returns the absolute path of a stored `.eml` file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$file` | `string` | File name as recorded by the capture or requested by the client. |

**Returns**

`string|null`: Path of the stored file, or `null` when the name carries a path segment or no such file exists.

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

```php
public function write(string $content): string
```

Writes one message to the mail directory under a new unique name.

A failure is logged and leaves no partial file behind, so the capture keeps the message without a stored file.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$content` | `string` | Message content, normally the RFC 5322 source of the sent message. |

**Returns**

`string`: Name of the written file, or `''` when it could not be written.