Directorytree Imapengine Laravel

https://github.com/directorytree/imapengine-laravel
Admin
ImapEngine provides a simple API for managing mailboxes without the PHP extension.
Tokens:24,446
Snippets:190
Trust Score:7.3
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Manual construction example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Shows how to manually create the event, useful for testing listeners.

```php
use DirectoryTree\ImapEngine\Laravel\Events\MailboxWatchAttemptsExceeded;

$event = new MailboxWatchAttemptsExceeded(
    'default',
    5,
    new RuntimeException('connection failed'),
    Date::now(),
);
```

--------------------------------

### Install ImapEngine for Laravel via Composer

Source: https://github.com/directorytree/imapengine-laravel/blob/master/README.md

Use this command to install the package into your Laravel project.

```bash
composer require directorytree/imapengine-laravel
```

--------------------------------

### WatchMailbox CLI usage examples

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-WatchMailbox.md

Examples of running the imap:watch command with different configurations for mailbox selection, monitoring methods, and retry settings.

```bash
# Watch the default mailbox's INBOX using IDLE
php artisan imap:watch default

# Watch a specific folder with polling, fetching message parts
php artisan imap:watch support INBOX --method=poll --with=flags,body,headers

# Increase the retry budget and timeout
php artisan imap:watch default --attempts=10 --timeout=60
```

--------------------------------

### Usage example: listening to the event

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Shows how to listen for the event and access its properties for alerting.

```php
use DirectoryTree\ImapEngine\Laravel\Events\MailboxWatchAttemptsExceeded;

Event::listen(function (MailboxWatchAttemptsExceeded $event) {
    $mailbox = $event->mailbox;                      // string
    $attempts = $event->attempts;                    // int
    $reason = $event->exception->getMessage();       // string
    $lastSeen = $event->lastReceivedAt;              // ?CarbonInterface

    // e.g. page an operator via your own service
    alertMailboxDown($mailbox, $reason, $lastSeen);
});
```

--------------------------------

### ConfigureIdleQuery No-op Example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-ConfigureIdleQuery.md

An empty configuration list results in a no-op, returning the query instance untouched.

```php
// No-op configuration (empty list) — passes the query through unmuted:
$noop = new ConfigureIdleQuery();

$query = $noop($mailbox->inbox()->messages()); // untouched MessageQueryInterface
```

--------------------------------

### forget() usage example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Shows how to drop a cached connection and then rebuild it from config.

```php
$manager->forget('default');      // drop cached connection
$fresh = $manager->mailbox('default'); // rebuilt from config
```

--------------------------------

### ConfigureIdleQuery Usage Example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-ConfigureIdleQuery.md

Demonstrates how to instantiate and invoke the class to configure a message query with specific parts.

```php
use DirectoryTree\ImapEngine\Laravel\Commands\ConfigureIdleQuery;

$configure = new ConfigureIdleQuery(['flags', 'body']);

$query = $configure($mailbox->inbox()->messages());

// Equivalent to the internal sequential calls:
// $query->withFlags();
// $query->withBody();
```

--------------------------------

### Example Usage of fake()

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

Demonstrates how to seed a fake mailbox with folders and messages for testing purposes.

```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMessage;

$inbox = new FakeFolder('inbox', ['\\HasNoChildren'], [
    new FakeMessage(1, ['\\Seen'], "From: sender@example.com\r\nSubject: Hello\r\n\r\nBody"),
]);

$fake = Imap::fake('default', [
    'host' => 'fake.example.com',
    'username' => 'user@example.com',
], [$inbox]);

// Application code now hits the fake:
$mailbox = Imap::mailbox('default');   // === $fake
$message = $mailbox->inbox()->messages()->find(1);
```

--------------------------------

### Usage example: resolving ImapManager and mailbox

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

Shows how to resolve the ImapManager singleton and obtain a mailbox instance.

```php
use DirectoryTree\ImapEngine\Laravel\ImapManager;

$manager = app(ImapManager::class); // singleton, lazily built from config('imap', [])

$mailbox = $manager->mailbox('default');
```

--------------------------------

### swap() usage example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Shows how to swap a cached mailbox with a FakeMailbox for testing. Subsequent mailbox() calls return the swapped instance.

```php
use DirectoryTree\ImapEngine\Testing\FakeMailbox;

$manager->swap('default', new FakeMailbox([
    'host' => 'imap.example.com',
    'username' => 'test@example.com',
]));

$fake = $manager->mailbox('default'); // $fake is the FakeMailbox
```

--------------------------------

### build() override example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Shows how to override build() in a subclass to return a custom Mailbox implementation, such as one with logging.

```php
class CustomManager extends ImapManager
{
    public function build(array $config): MailboxInterface
    {
        return new MyInstrumentedMailbox($config); // e.g. adds logging
    }
}
```

--------------------------------

### Manual HandleMessageReceived Instantiation

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-HandleMessageReceived.md

Example of manually instantiating and using the callback outside of the standard WatchMailbox command flow.

```php
use DirectoryTree\ImapEngine\Laravel\Commands\HandleMessageReceived;
use DirectoryTree\ImapEngine\Laravel\Commands\WatchMailbox;

$attempts = 0;
$lastReceivedAt = null;

$handle = new HandleMessageReceived($command, 'default', $attempts, $lastReceivedAt);

$folder->idle($handle); // ImapEngine invokes $handle($message) per message
```

--------------------------------

### mailbox() usage example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Shows how to instantiate ImapManager and retrieve a mailbox. The first call builds and caches the instance, the second call returns the cached instance.

```php
use DirectoryTree\ImapEngine\Laravel\ImapManager;

$manager = new ImapManager(config('imap'));

$mailbox = $manager->mailbox('default'); // builds + caches

$same = $manager->mailbox('default');    // cache hit, same instance
```

--------------------------------

### register() usage example

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Shows how to register multiple mailboxes with register() and then retrieve one with mailbox(). The registered mailbox is cached and can be retrieved by mailbox().

```php
$manager
    ->register('work', [
        'host' => 'imap.work.example.com',
        'port' => 993,
        'username' => 'user@work.example.com',
        'password' => 'secret',
        'encryption' => 'ssl',
    ])
    ->register('personal', [
        'host' => 'imap.personal.example.com',
        'port' => 993,
        'username' => 'user@personal.example.com',
        'password' => 'secret',
        'encryption' => 'ssl',
    ]);

$work = $manager->mailbox('work'); // cached instance created by register()
```

--------------------------------

### Injecting LoopInterface into a Consumer

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

Example of type-hinting the LoopInterface in a class constructor for dependency injection.

```php
use DirectoryTree\ImapEngine\Laravel\Support\LoopInterface;

class MailboxWatcher
{
    public function __construct(private LoopInterface $loop) {}

    public function watch(callable $tick): void
    {
        $this->loop->run($tick);
    }
}

// In tests: App::bind(LoopInterface::class, LoopFake::class)
```

--------------------------------

### Listen for MessageReceived events

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-WatchMailbox.md

Example of how to handle incoming messages by listening for the MessageReceived event within a Laravel application.

```php
// Application-side: react to messages by listening for the dispatched event.
use DirectoryTree\ImapEngine\Laravel\Events\MessageReceived;

Event::listen(function (MessageReceived $event) {
    $message = $event->message;   // MessageInterface
    $mailbox = $event->mailbox;   // string
});
```

--------------------------------

### Manually construct and dispatch MessageReceived

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MessageReceived.md

Creates a MessageReceived event manually and dispatches it, useful for re-dispatching or unit-testing downstream listeners. The mailbox is set to 'default' in this example.

```php
use DirectoryTree\ImapEngine\Laravel\Events\MessageReceived;
use Illuminate\Support\Facades\Event;

$event = new MessageReceived($message, 'default');

Event::dispatch($event);
```

--------------------------------

### boot() implementation

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

Registers the WatchMailbox command in console and publishes the config file.

```php
if ($this->app->runningInConsole()) {
    $this->commands([
        Commands\WatchMailbox::class,
    ]);
}

$this->publishes([
    __DIR__.'/../config/imap.php' => config_path('imap.php'),
]);
```

--------------------------------

### boot() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

Declares the boot() method that registers commands and publishes config.

```php
/**
 * Bootstrap application services.
 */
public function boot(): void
```

--------------------------------

### ConfigureIdleQuery Constructor

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-ConfigureIdleQuery.md

The constructor accepts an array of message parts to fetch, defaulting to an empty list.

```php
/**
 * Constructor.
 */
public function __construct(
    protected array $with = []
) {}
```

--------------------------------

### Mailbox Resolution and Swapping

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

Demonstrates resolving a mailbox and swapping the connection configuration at runtime.

```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;

$inbox = Imap::mailbox('default')->inbox();       // facade proxy to ImapManager::mailbox()

$messages = $inbox->messages()->get();

// Swap a long-lived connection with a re-created one at runtime:
Imap::swap('default', new Mailbox([...new connection config...]));
```

--------------------------------

### ConfigureIdleQuery Usage within WatchMailbox

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-ConfigureIdleQuery.md

Shows how the class is integrated into the WatchMailbox command to process CLI options.

```php
$with = explode(',', $this->option('with'));

$folder->idle(
    new HandleMessageReceived($this, $name, $attempts, $lastReceivedAt),
    new ConfigureIdleQuery($with),
    $this->option('timeout'),
);
```

--------------------------------

### ImapManager::build

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Builds a mailbox instance from the given configuration.

```APIDOC
## ImapManager::build

### Description
Builds a mailbox instance from the given configuration.

### Method
build

### Parameters
- **config** (array) - Required - Configuration array for the mailbox.

### Returns
- **MailboxInterface** - The built mailbox instance.
```

--------------------------------

### Manual Loop Usage

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

Direct instantiation and usage of the Loop class.

```php
use DirectoryTree\ImapEngine\Laravel\Support\Loop;

$loop = new Loop;

$loop->run(function () {
    // do work forever
});
```

--------------------------------

### register() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

Declares the register() method that binds container services.

```php
/**
 * Register application services.
 */
public function register(): void
```

--------------------------------

### ConfigureIdleQuery::__invoke

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Configures an idle query for message retrieval.

```APIDOC
## ConfigureIdleQuery::__invoke

### Description
Configures an idle query for message retrieval.

### Method
__invoke

### Parameters
- **query** (MessageQueryInterface) - Required - The message query to configure.

### Returns
- **MessageQueryInterface** - The configured query.
```

--------------------------------

### Loop::run / LoopFake::run

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Runs the event loop with a callback.

```APIDOC
## Loop::run / LoopFake::run

### Description
Runs the event loop with a callback.

### Method
run

### Parameters
- **callback** (callable) - Required - The callback to execute.

### Returns
- **void**
```

--------------------------------

### swap() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Defines the swap() method that replaces a cached mailbox instance. It returns void.

```php
/**
 * Swap out a mailbox instance with a new one.
 */
public function swap(string $name, MailboxInterface $mailbox): void
```

--------------------------------

### build() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Defines the build() method that creates a new Mailbox instance. It does not cache, and can be overridden in subclasses.

```php
/**
 * Build an on-demand mailbox instance.
 */
public function build(array $config): MailboxInterface
```

--------------------------------

### register(string $name, array $config): static

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Registers a mailbox instance with the given config. Builds the mailbox via build() and stores it in the in-memory cache. Does not consult the global config, allowing on-demand registration.

```APIDOC
## register(string $name, array $config): static

### Description
Register a mailbox instance. Builds a mailbox from the given config via build() and stores it in the in-memory cache under name. Unlike mailbox(), this does not consult $this->config - the config is applied directly. The registered mailbox can be retrieved by mailbox() afterwards since the cache is checked first.

### Method
register

### Signature
public function register(string $name, array $config): static

### Parameters
- **name** (string) - Required - The mailbox name to register.
- **config** (array) - Required - Mailbox connection config (same schema as a config/imap.php mailbox entry).

### Return Type
static - returns $this, enabling fluent chaining.

### Example
```php
$manager
    ->register('work', [
        'host' => 'imap.work.example.com',
        'port' => 993,
        'username' => 'user@work.example.com',
        'password' => 'secret',
        'encryption' => 'ssl',
    ])
    ->register('personal', [
        'host' => 'imap.personal.example.com',
        'port' => 993,
        'username' => 'user@personal.example.com',
        'password' => 'secret',
        'encryption' => 'ssl',
    ]);

$work = $manager->mailbox('work'); // cached instance created by register()
```
```

--------------------------------

### Facades\Imap::fake

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Creates a fake mailbox for testing purposes.

```APIDOC
## Facades\Imap::fake

### Description
Creates a fake mailbox for testing purposes.

### Method
fake

### Parameters
- **name** (string) - Required - The name of the fake mailbox.
- **config** (array) - Required - Configuration array.
- **options** (array) - Required - Additional options.
- **overrides** (array) - Required - Overrides for the fake.

### Returns
- **FakeMailbox** - The fake mailbox instance.
```

--------------------------------

### ConfigureIdleQuery __invoke Method Signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-ConfigureIdleQuery.md

The __invoke method accepts a MessageQueryInterface and returns the same instance after applying the configured mutators.

```php
/**
 * Configure the query.
 */
public function __invoke(MessageQueryInterface $query): MessageQueryInterface
```

--------------------------------

### HandleMessageReceived Constructor

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-HandleMessageReceived.md

The constructor accepts the owning command, mailbox name, and two reference parameters for tracking retry state and the last received timestamp.

```php
/**
 * Constructor.
 */
public function __construct(
    protected WatchMailbox $command,
    protected string $mailbox,
    protected int &$attempts = 0,
    protected ?CarbonInterface &$lastReceivedAt = null,
) {}
```

--------------------------------

### Loop Implementation

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

The default production implementation that executes the provided callable indefinitely.

```php
class Loop implements LoopInterface
{
    /**
     * {@inheritDoc}
     */
    public function run(callable $tick): void
    {
        while (true) {
            $tick();
        }
    }
}
```

--------------------------------

### Facade Proxy Method Declarations

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

The docblock defining the proxied methods available on the Imap facade.

```php
/**
 * @method static \DirectoryTree\ImapEngine\MailboxInterface mailbox(string $name)
 * @method static \DirectoryTree\ImapEngine\MailboxInterface swap(string $name, \DirectoryTree\ImapEngine\MailboxInterface $mailbox)
 */
```

--------------------------------

### register() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Defines the register() method that registers a mailbox instance. It returns $this for fluent chaining.

```php
/**
 * Register a mailbox instance.
 */
public function register(string $name, array $config): static
```

--------------------------------

### IMAP Configuration File Structure

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/configuration.md

The configuration file uses a mailboxes key to map mailbox names to their respective connection settings. Additional mailboxes can be defined by adding new keys alongside the default configuration.

```php
return [
    'mailboxes' => [
        'default' => [
            'port'          => env('IMAP_PORT', 993),
            'host'          => env('IMAP_HOST'),
            'timeout'       => env('IMAP_TIMEOUT', 30),
            'debug'         => env('IMAP_DEBUG', false),
            'username'      => env('IMAP_USERNAME'),
            'password'      => env('IMAP_PASSWORD'),
            'encryption'    => env('IMAP_ENCRYPTION', 'ssl'),
            'validate_cert' => env('IMAP_VALIDATE_CERT', true),
            'authentication'=> env('IMAP_AUTHENTICATION', 'plain'),
            'proxy' => [
                'socket'          => env('IMAP_PROXY_SOCKET'),
                'username'        => env('IMAP_PROXY_USERNAME'),
                'password'        => env('IMAP_PROXY_PASSWORD'),
                'request_fulluri' => env('IMAP_PROXY_REQUEST_FULLURI', false),
            ],
        ],
    ],
];
```

--------------------------------

### fake Method Implementation

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

The internal implementation logic for the fake() method.

```php
$manager = static::getFacadeRoot();
$fake = new FakeMailbox($config, $folders, $capabilities);
$manager->swap($mailbox, $fake);
return $fake;
```

--------------------------------

### Dispatch logic in WatchMailbox command

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Shows the condition that triggers the event when attempts reach the limit, then rethrows the exception.

```php
if ($attempts >= $this->option('attempts')) {
    $this->info("Exception: {$e->getMessage()}");

    Event::dispatch(
        new MailboxWatchAttemptsExceeded($name, $attempts, $e, $lastReceivedAt)
    );

    throw $e;
}

$attempts++;
```

--------------------------------

### ImapManager::__construct(array $config)

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Constructor that stores the IMAP configuration array and initializes an empty mailbox cache. No validation is performed at construction.

```APIDOC
## ImapManager::__construct(array $config)

### Description
Constructor that stores the IMAP configuration array and initializes an empty mailbox cache. No validation is performed at construction.

### Method
Constructor

### Signature
```php
public function __construct(array $config)
```

### Parameters
- **config** (array) - Required - The IMAP configuration array. Must contain a `mailboxes` key mapping mailbox names to mailbox config arrays (`config('imap', [])` at registration time).

### Notes
- The constructor stores `$this->config = $config` and initializes an empty `$this->mailboxes` cache.
- No validation is performed at construction.
```

--------------------------------

### getFacadeAccessor Method

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

The protected method that returns the container key for the facade.

```php
/**
 * Get the registered name of the component.
 */
protected static function getFacadeAccessor(): string
```

--------------------------------

### Composer auto-discovery configuration for ImapServiceProvider

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

JSON configuration in composer.json that enables Laravel package auto-discovery for the ImapServiceProvider.

```json
{
    "extra": {
        "laravel": {
            "providers": [
                "DirectoryTree\\ImapEngine\\Laravel\\ImapServiceProvider"
            ]
        }
    }
}
```

--------------------------------

### Imap::fake()

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

Creates a FakeMailbox instance, swaps it into the manager's cache under the given name, and returns it. This allows application code to run unchanged against fake mailboxes.

```APIDOC
## Imap::fake()

### Description
Creates a FakeMailbox instance with the given configuration, folders, and capabilities, swaps it into the manager's cache under the specified mailbox name, and returns the fake. This allows application code to run unchanged against fake mailboxes.

### Method
static

### Signature
```php
public static function fake(
    string $mailbox,
    array $config = [],
    array $folders = [],
    array $capabilities = []
): FakeMailbox
```

### Parameters
- **mailbox** (string) - Required - The mailbox name. It need not exist in the IMAP config; the fake is swapped into the manager's cache under this name.
- **config** (array) - Optional - Config array passed to the FakeMailbox constructor (e.g. ['host' => ...]).
- **folders** (array) - Optional - Initial FakeFolder instances (from DirectoryTree\ImapEngine\Testing) seeded into the mailbox.
- **capabilities** (array) - Optional - IMAP capability strings passed to the FakeMailbox constructor.

### Return Value
- **FakeMailbox** (DirectoryTree\ImapEngine\Testing\FakeMailbox) - The created fake mailbox instance.

### Example
```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;
use DirectoryTree\ImapEngine\Testing\FakeFolder;
use DirectoryTree\ImapEngine\Testing\FakeMessage;

$inbox = new FakeFolder('inbox', ['\\HasNoChildren'], [
    new FakeMessage(1, ['\\Seen'], "From: sender@example.com\r\nSubject: Hello\r\n\r\nBody"),
]);

$fake = Imap::fake('default', [
    'host' => 'fake.example.com',
    'username' => 'user@example.com',
], [$inbox]);

// Application code now hits the fake:
$mailbox = Imap::mailbox('default');   // === $fake
$message = $mailbox->inbox()->messages()->find(1);
```

### Error Handling
fake() itself never throws for missing mailbox names (the fake is inserted regardless).
```

--------------------------------

### build(array $config): MailboxInterface

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Factory method that creates a new Mailbox instance from the given config. Does not cache; caching is the caller's responsibility. Can be overridden in subclasses to substitute a different Mailbox implementation.

```APIDOC
## build(array $config): MailboxInterface

### Description
Build an on-demand mailbox instance. The factory method: return new Mailbox($config); where Mailbox is DirectoryTree\ImapEngine\Mailbox. It does not cache - caching is the caller's responsibility. Override this in a subclass to substitute a different Mailbox implementation.

### Method
build

### Signature
public function build(array $config): MailboxInterface

### Parameters
- **config** (array) - Required - Mailbox connection config array.

### Return Type
MailboxInterface

### Example
```php
class CustomManager extends ImapManager
{
    public function build(array $config): MailboxInterface
    {
        return new MyInstrumentedMailbox($config); // e.g. adds logging
    }
}
```
```

--------------------------------

### MessageReceived constructor with promoted properties

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MessageReceived.md

Defines the public constructor of the MessageReceived event, promoting $message and $mailbox to public properties. Both parameters are required; $message is a MessageInterface and $mailbox is a string.

```php
public function __construct(
    public MessageInterface $message,
    public string $mailbox,
) {}
```

--------------------------------

### Imap::swap()

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

Facade proxy to ImapManager::swap(). Swaps the mailbox with the given name with a new mailbox instance.

```APIDOC
## Imap::swap()

### Description
Facade proxy to ImapManager::swap(). Swaps the mailbox with the given name with a new mailbox instance.

### Method
static

### Signature
```php
public static function swap(string $name, \DirectoryTree\ImapEngine\MailboxInterface $mailbox): \DirectoryTree\ImapEngine\MailboxInterface
```

### Parameters
- **name** (string) - Required - The mailbox name.
- **mailbox** (MailboxInterface) - Required - The new mailbox instance to swap in.

### Return Value
- **MailboxInterface** (DirectoryTree\ImapEngine\MailboxInterface) - The swapped mailbox instance.

### Example
```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;

// Swap a long-lived connection with a re-created one at runtime:
Imap::swap('default', new Mailbox([...new connection config...]));
```
```

--------------------------------

### ImapManager::__construct

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Constructor for the ImapManager class, accepting a configuration array.

```APIDOC
## ImapManager::__construct

### Description
Initializes a new ImapManager instance with the provided configuration array.

### Method
Constructor

### Parameters
- **config** (array) - Required - Configuration array for the IMAP connection.

### Returns
None
```

--------------------------------

### Listening to the Event

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Shows how to register a listener for the MailboxWatchAttemptsExceeded event and access its public properties.

```APIDOC
## Listening to MailboxWatchAttemptsExceeded

### Description
Register a listener to handle the event when the imap:watch command exceeds its retry attempts. Access the event's public properties directly.

### Usage Example
```php
use DirectoryTree\ImapEngine\Laravel\Events\MailboxWatchAttemptsExceeded;

Event::listen(function (MailboxWatchAttemptsExceeded $event) {
    $mailbox = $event->mailbox;                      // string
    $attempts = $event->attempts;                    // int
    $reason = $event->exception->getMessage();       // string
    $lastSeen = $event->lastReceivedAt;              // ?CarbonInterface

    // e.g. page an operator via your own service
    alertMailboxDown($mailbox, $reason, $lastSeen);
});
```

### Properties
- **mailbox** (string) - The name of the mailbox being watched.
- **attempts** (int) - The retry counter value at the threshold.
- **exception** (Exception) - The triggering exception.
- **lastReceivedAt** (?CarbonInterface) - Timestamp of last received message, or null.

### Error Handling
Listeners should not throw exceptions, as they would replace the original exception rethrown by WatchMailbox.
```

--------------------------------

### mailbox($name)

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Retrieves a mailbox instance by its configured name. Throws an InvalidArgumentException if the name is not defined in the configuration.

```APIDOC
## mailbox($name)

### Description
Retrieves a mailbox instance by its configured name. Throws an InvalidArgumentException if the name is not defined in the configuration.

### Method
mailbox

### Parameters
- **$name** (string) - Required - The name of the mailbox as defined in the configuration.

### Throws
- **InvalidArgumentException** - If the mailbox name is not present in the configuration. Message: `Mailbox [{$name}] is not defined. Please check your IMAP configuration.`

### Notes
- The manager is a singleton binding in the Laravel container, so callers can request MailboxInterface directly.
- See the full error catalog in errors.md for catch patterns.
```

--------------------------------

### swap(string $name, MailboxInterface $mailbox): void

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Swaps out a mailbox instance with a new one. Overwrites the cache slot unconditionally, without consulting the config. Used by Imap::fake() to inject test doubles.

```APIDOC
## swap(string $name, MailboxInterface $mailbox): void

### Description
Swap out a mailbox instance with a new one. Overwrites the cache slot unconditionally - the config is not consulted. This is the mechanism used by Imap::fake() to inject FakeMailbox test doubles and by ImapManager::register()-style flows. Because mailbox() checks the cache before the config, the swapped instance is returned by subsequent mailbox($name) calls.

### Method
swap

### Signature
public function swap(string $name, MailboxInterface $mailbox): void

### Parameters
- **name** (string) - Required - The mailbox name whose cached instance is replaced.
- **mailbox** (MailboxInterface) - Required - The replacement instance.

### Return Type
void

### Example
```php
use DirectoryTree\ImapEngine\Testing\FakeMailbox;

$manager->swap('default', new FakeMailbox([
    'host' => 'imap.example.com',
    'username' => 'test@example.com',
]));

$fake = $manager->mailbox('default'); // $fake is the FakeMailbox
```
```

--------------------------------

### fake Method Signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

The static method signature for creating a fake mailbox for testing.

```php
/**
 * Fake the given mailbox.
 */
public static function fake(
    string $mailbox,
    array $config = [],
    array $folders = [],
    array $capabilities = []
): FakeMailbox
```

--------------------------------

### Container bindings in register()

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapServiceProvider.md

Registers ImapManager as a singleton and binds LoopInterface to Loop.

```php
$this->app->singleton(ImapManager::class, function () {
    return new ImapManager(config('imap', []));
});

$this->app->bind(LoopInterface::class, Loop::class);
```

--------------------------------

### mailbox() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Defines the mailbox() method that returns a MailboxInterface instance. It checks the cache first, then builds from config if the name exists, otherwise throws InvalidArgumentException.

```php
/**
 * Get a mailbox instance.
 */
public function mailbox(string $name): MailboxInterface
```

--------------------------------

### ImapManager::swap

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Swaps the implementation for a given mailbox name with a custom instance.

```APIDOC
## ImapManager::swap

### Description
Swaps the implementation for a given mailbox name with a custom instance.

### Method
swap

### Parameters
- **name** (string) - Required - The name of the mailbox.
- **mailbox** (MailboxInterface) - Required - The custom mailbox instance.

### Returns
- **void**
```

--------------------------------

### WatchMailbox::handle

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Handles the mailbox watching loop.

```APIDOC
## WatchMailbox::handle

### Description
Handles the mailbox watching loop.

### Method
handle

### Parameters
- **loop** (LoopInterface) - Required - The event loop interface.

### Returns
- **void**
```

--------------------------------

### LoopFake Implementation

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

A deterministic test double that executes the provided callable exactly once.

```php
class LoopFake implements LoopInterface
{
    /**
     * {@inheritDoc}
     */
    public function run(callable $tick): void
    {
        $tick();
    }
}
```

--------------------------------

### LoopFake::run(callable $tick): void

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

Deterministic single-iteration double. It invokes $tick exactly once and returns, used for testing successful-watch scenarios.

```APIDOC
## LoopFake::run(callable $tick): void

### Description
Deterministic single-iteration double. If `$tick` throws, the exception propagates from `run()` immediately (no retry loop).

### Method
run

### Signature
`run(callable $tick): void`

### Parameters
- **tick** (callable) - Required - The watch body; invoked exactly once.

### Return Type
`void` — returns after a single tick.

### Usage Example
```php
// In tests: App::bind(LoopInterface::class, LoopFake::class)
```
```

--------------------------------

### Constructor of MailboxWatchAttemptsExceeded

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Defines the public properties: mailbox, attempts, exception, and lastReceivedAt. All are constructor-promoted and publicly accessible.

```php
/**
 * Constructor.
 */
public function __construct(
    public string $mailbox,
    public int $attempts,
    public Exception $exception,
    public ?CarbonInterface $lastReceivedAt = null,
) {}
```

--------------------------------

### Register ImapManager and LoopInterface in ServiceProvider

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/configuration.md

Shows the registration of the ImapManager singleton and LoopInterface binding within a Laravel ServiceProvider or bootstrap file. This is typically handled automatically by package auto-discovery.

```php
// In the application's ServiceProvider or bootstrap file (already handled by package auto-discovery):
// provider: DirectoryTree\ImapEngine\Laravel\ImapServiceProvider
$this->app->singleton(ImapManager::class, fn () => new ImapManager(config('imap', [])));
$this->app->bind(LoopInterface::class, Loop::class);
```

--------------------------------

### mailbox(string $name): MailboxInterface

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Retrieves a mailbox instance by name. Returns the cached instance if present, otherwise builds and caches it from the config. Throws InvalidArgumentException if the name is not defined in the config.

```APIDOC
## mailbox(string $name): MailboxInterface

### Description
Get a mailbox instance. Returns the cached instance if present. Otherwise, if the name exists in config['mailboxes'], it builds the mailbox via build() and stores it in the cache before returning. If the name is not defined in the config, it throws InvalidArgumentException.

### Method
mailbox

### Signature
public function mailbox(string $name): MailboxInterface

### Parameters
- **name** (string) - Required - The mailbox name as keyed in config['mailboxes'].

### Return Type
MailboxInterface (DirectoryTree\ImapEngine\MailboxInterface) - a fully constructed ImapEngine mailbox.

### Example
```php
use DirectoryTree\ImapEngine\Laravel\ImapManager;

$manager = new ImapManager(config('imap'));

$mailbox = $manager->mailbox('default'); // builds + caches

$same = $manager->mailbox('default');    // cache hit, same instance
```
```

--------------------------------

### HandleMessageReceived Usage in WatchMailbox

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-HandleMessageReceived.md

Typically, this class is instantiated within the WatchMailbox::handle method to wire the callback into the idle loop.

```php
$folder->idle(
    new HandleMessageReceived($this, $name, $attempts, $lastReceivedAt),
    new ConfigureIdleQuery($with),
    $this->option('timeout'),
);
```

--------------------------------

### Loop::run(callable $tick): void

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

The default infinite-loop implementation. It iterates $tick() forever inside a while(true) loop, exiting only if $tick throws.

```APIDOC
## Loop::run(callable $tick): void

### Description
The default implementation; runs indefinitely, which is the intended production behavior. It catches nothing and holds no state.

### Method
run

### Signature
`run(callable $tick): void`

### Parameters
- **tick** (callable) - Required - The watch body; invoked repeatedly until it throws.

### Return Type
`void` — never returns normally; iterates `$tick()` forever inside `while (true)`. The loop exits only if `$tick` throws — the exception propagates out of `run()`.

### Usage Example
```php
use DirectoryTree\ImapEngine\Laravel\Support\Loop;

$loop = new Loop;

$loop->run(function () {
    // do work forever
});
```
```

--------------------------------

### ImapManager::mailbox

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Retrieves a mailbox instance by its name.

```APIDOC
## ImapManager::mailbox

### Description
Retrieves a mailbox instance by its name.

### Method
mailbox

### Parameters
- **name** (string) - Required - The name of the mailbox.

### Returns
- **MailboxInterface** - The mailbox instance.
```

--------------------------------

### Listen to MessageReceived event

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MessageReceived.md

Registers a listener for the MessageReceived event, accessing the message UID and mailbox name from the event properties. Use this to react to incoming mail, e.g., to notify or persist.

```php
use DirectoryTree\ImapEngine\Laravel\Events\MessageReceived;

Event::listen(function (MessageReceived $event) {
    $uid     = $event->message->uid();   // the message UID as an int-like value
    $mailbox = $event->mailbox;          // the mailbox name string

    // e.g. record the received message via your own application service
    notifyIncomingMail($mailbox, $uid);
});
```

--------------------------------

### Imap::mailbox()

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Facades-Imap.md

Facade proxy to ImapManager::mailbox(). Resolves the mailbox with the given name from the manager's cache or configuration.

```APIDOC
## Imap::mailbox()

### Description
Facade proxy to ImapManager::mailbox(). Resolves the mailbox with the given name from the manager's cache or configuration.

### Method
static

### Signature
```php
public static function mailbox(string $name): \DirectoryTree\ImapEngine\MailboxInterface
```

### Parameters
- **name** (string) - Required - The mailbox name.

### Return Value
- **MailboxInterface** (DirectoryTree\ImapEngine\MailboxInterface) - The resolved mailbox instance.

### Example
```php
use DirectoryTree\ImapEngine\Laravel\Facades\Imap;

$inbox = Imap::mailbox('default')->inbox();
$messages = $inbox->messages()->get();
```

### Error Handling
Throws InvalidArgumentException when the name is absent from both the config and the cache.
```

--------------------------------

### MailboxWatchAttemptsExceeded Constructor

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MailboxWatchAttemptsExceeded.md

Creates a new MailboxWatchAttemptsExceeded event instance with the mailbox name, retry count, exception, and optional last received timestamp.

```APIDOC
## MailboxWatchAttemptsExceeded Constructor

### Description
Creates a new MailboxWatchAttemptsExceeded event instance. All parameters are constructor-promoted public properties.

### Method
Constructor

### Signature
```php
public function __construct(
    public string $mailbox,
    public int $attempts,
    public Exception $exception,
    public ?CarbonInterface $lastReceivedAt = null,
) {}
```

### Parameters
- **mailbox** (string) - Required - The name of the mailbox being watched (the `mailbox` argument of `imap:watch`).
- **attempts** (int) - Required - The retry counter value at the moment the threshold was reached (equals the `--attempts` option value in the dispatch path).
- **exception** (Exception) - Required - The exception that failed to be classified as message-missing/disconnection and persisted across retries.
- **lastReceivedAt** (?CarbonInterface) - Optional - Default: `null` - Timestamp of the last message received before failures began; `null` when no message was ever received.

### Usage Example
```php
use DirectoryTree\ImapEngine\Laravel\Events\MailboxWatchAttemptsExceeded;

$event = new MailboxWatchAttemptsExceeded(
    'default',
    5,
    new RuntimeException('connection failed'),
    Date::now(),
);
```
```

--------------------------------

### LoopInterface::run(callable $tick): void

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

The interface method that executes the loop. The contract leaves iteration semantics to the implementation.

```APIDOC
## LoopInterface::run(callable $tick): void

### Description
Executes the loop. The contract leaves iteration semantics (bounded vs unbounded) to the implementation.

### Method
run

### Signature
`run(callable $tick): void`

### Parameters
- **tick** (callable) - Required - The watch body; invoked repeatedly until it throws.

### Return Type
`void`

### Usage Example
```php
use DirectoryTree\ImapEngine\Laravel\Support\LoopInterface;

class MailboxWatcher
{
    public function __construct(private LoopInterface $loop) {}

    public function watch(callable $tick): void
    {
        $this->loop->run($tick);
    }
}
```
```

--------------------------------

### HandleMessageReceived::__invoke

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Handles a received message.

```APIDOC
## HandleMessageReceived::__invoke

### Description
Handles a received message.

### Method
__invoke

### Parameters
- **message** (MessageInterface) - Required - The received message.

### Returns
- **void**
```

--------------------------------

### forget(string $name): static

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Removes a mailbox from the in-memory cache. The config entry is left untouched, so a subsequent mailbox() call would rebuild the instance. Does not throw if the name was not cached.

```APIDOC
## forget(string $name): static

### Description
Remove a mailbox from the in-memory cache. Runs unset($this->mailboxes[$name]); the config entry is left untouched, so a subsequent mailbox() call would rebuild the instance. Does not throw if the name was not cached.

### Method
forget

### Signature
public function forget(string $name): static

### Parameters
- **name** (string) - Required - The mailbox name to evict from the cache.

### Return Type
static - returns $this.

### Example
```php
$manager->forget('default');      // drop cached connection
$fresh = $manager->mailbox('default'); // rebuilt from config
```
```

--------------------------------

### Registering LoopInterface in ImapServiceProvider

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Support-Loop.md

Binds the LoopInterface to the infinite-loop Loop implementation within the Laravel service provider.

```php
$this->app->bind(LoopInterface::class, Loop::class);
```

--------------------------------

### LoopInterface definition

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

The LoopInterface defines the contract for executing the loop, with iteration semantics determined by the implementation.

```php
interface LoopInterface
{
    /**
     * Execute the loop.
     */
    public function run(callable $tick): void;
}
```

--------------------------------

### HandleMessageReceived __invoke Method

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-HandleMessageReceived.md

The __invoke method is called by ImapEngine for each message received. It logs the message UID, resets the retry counter, updates the timestamp, and dispatches the MessageReceived event.

```php
/**
 * Handle the message received event.
 */
public function __invoke(MessageInterface $message): void
```

--------------------------------

### ImapManager::register

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Registers a custom mailbox implementation with the manager.

```APIDOC
## ImapManager::register

### Description
Registers a custom mailbox implementation with the manager.

### Method
register

### Parameters
- **name** (string) - Required - The name of the mailbox.
- **config** (array) - Required - Configuration array for the mailbox.

### Returns
- **static** - Returns the current instance for chaining.
```

--------------------------------

### forget() method signature

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/ImapManager.md

Defines the forget() method that removes a mailbox from the in-memory cache. It returns $this.

```php
/**
 * Remove a mailbox from the in-memory cache.
 */
public function forget(string $name): static
```

--------------------------------

### Catch InvalidArgumentException and InvalidOptionException in consumer code

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/errors.md

Standard try/catch pattern for consumer code that calls ImapManager::mailbox('primary'). Catches InvalidArgumentException from the mailbox call; InvalidOptionException is imported but not used in the shown block.

```php
use InvalidArgumentException;
use Symfony\Component\Console\Exception\InvalidOptionException;

try {
    $mailbox = app(ImapManager::class)->mailbox('primary');
} catch (InvalidArgumentException $e) {
    // handle
}
```

--------------------------------

### imap:watch

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Commands-WatchMailbox.md

Watches a mailbox folder for new messages using IMAP IDLE or polling. Dispatches MessageReceived for each message and MailboxWatchAttemptsExceeded when retries are exhausted.

```APIDOC
## imap:watch

### Description
Watches a mailbox folder for new messages using IMAP IDLE or polling. Dispatches the `MessageReceived` event for each message and the `MailboxWatchAttemptsExceeded` event when retries are exhausted.

### Method
Artisan Command

### Endpoint
`php artisan imap:watch {mailbox} {folder?} [options]`

### Parameters
#### Arguments
- **mailbox** (string) - Required - The mailbox name, resolved via `Imap::mailbox($name)`; must be defined in the IMAP config (or pre-registered/faked), else `InvalidArgumentException`.
- **folder** (string) - Optional - The folder to watch. When omitted, the mailbox's INBOX is used (`$mailbox->inbox()`).

#### Options
- **--method** (string) - Optional - Default: `idle` - Watch method. Must be `idle` or `poll`, else `InvalidOptionException`.
- **--with** (string) - Optional - Default: `''` - Comma-separated message parts to fetch; each part is matched against `flags`, `body`, `headers` by `ConfigureIdleQuery`.
- **--timeout** (int) - Optional - Default: `30` - The timeout in minutes; passed through as third argument to `$folder->idle(...)`/`$folder->poll(...)`.
- **--attempts** (int) - Optional - Default: `5` - Maximum number of retry attempts before the `MailboxWatchAttemptsExceeded` event is dispatched and the loop aborts with the underlying exception.
- **--debug** (bool) - Optional - Default: `false` - Enable debug mode (declared in the signature; not read by `handle()` in the current source).

### Request Example
```bash
php artisan imap:watch my-mailbox --method=poll --with=flags,body --timeout=15 --attempts=3
```

### Response
#### Success Response
No explicit response body. The command runs as a long-running process, dispatching events.

#### Events Dispatched
- **MessageReceived** - Dispatched for each new message found.
- **MailboxWatchAttemptsExceeded** - Dispatched when retry attempts are exhausted.

### Error Handling
- **InvalidArgumentException** - Thrown when the mailbox is not defined in the IMAP config.
- **InvalidOptionException** - Thrown when `--method` is not `idle` or `poll`.
```

--------------------------------

### Dispatch MessageReceived event in HandleMessageReceived

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/api-reference/Events-MessageReceived.md

Dispatches the MessageReceived event with the given message and the mailbox name. This is the only dispatch point for this event, called from HandleMessageReceived::__invoke().

```php
Event::dispatch(new MessageReceived($message, $this->mailbox));
```

--------------------------------

### ImapManager::forget

Source: https://github.com/directorytree/imapengine-laravel/blob/master/_autodocs/types.md

Removes a registered mailbox from the manager.

```APIDOC
## ImapManager::forget

### Description
Removes a registered mailbox from the manager.

### Method
forget

### Parameters
- **name** (string) - Required - The name of the mailbox to forget.

### Returns
- **static** - Returns the current instance for chaining.
```
Tokens:
Raw