Laravel IMAP

https://github.com/webklex/laravel-imap
Admin
Laravel IMAP is a library that integrates the native php-imap module and a custom IMAP protocol into...
Tokens:22,940
Snippets:165
Trust Score:8.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### PHP code example in README

Source: https://github.com/webklex/laravel-imap/blob/master/README.md

Example of PHP code formatting in a GitHub issue. The source shows how to format code with triple backticks.

```php
echo 'your php code...';
```

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

### Install laravel-imap via Composer

Source: https://github.com/webklex/laravel-imap/blob/master/README.md

Adds the webklex/laravel-imap package to the project using Composer.

```bash
composer require webklex/laravel-imap
```

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

### Connect to IMAP and process all messages

Source: https://github.com/webklex/laravel-imap/blob/master/README.md

Basic example that connects to the default IMAP account, iterates through all folders and messages, prints subject, attachment count, and HTML body, then moves each message to 'INBOX.read'. Not intended for production use.

```php
/** @var \Webklex\PHPIMAP\Client $client */
$client = Webklex\IMAP\Facades\Client::account('default');

//Connect to the IMAP Server
$client->connect();

//Get all Mailboxes
/** @var \Webklex\PHPIMAP\Support\FolderCollection $folders */
$folders = $client->getFolders();

//Loop through every Mailbox
/** @var \Webklex\PHPIMAP\Folder $folder */
foreach($folders as $folder){

    //Get all Messages of the current Mailbox $folder
    /** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
    $messages = $folder->messages()->all()->get();
    
    /** @var \Webklex\PHPIMAP\Message $message */
    foreach($messages as $message){
        echo $message->getSubject().'<br />';
        echo 'Attachments: '.$message->getAttachments()->count().'<br />';
        echo $message->getHTMLBody();
        
        //Move the current Message to 'INBOX.read'
        if($message->move('INBOX.read') == true){
            echo 'Message has been moved';
        }else{
            echo 'Message could not be moved';
        }
    }
}
```

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

### Install mbstring PHP module

Source: https://github.com/webklex/laravel-imap/blob/master/README.md

Required before installing the library. The laravel-imap package depends on the mbstring PHP extension.

```bash
sudo apt-get install php*-mbstring
```

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

### Basic Usage with Named Default Account

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/client-facade.md

Shows how to use Client::account('default') to get a client instance, connect to the IMAP server, and retrieve all mailboxes. The account name must be configured in config('imap.accounts').

```php
<?php

use Webklex\IMAP\Facades\Client;

/** @var \Webklex\PHPIMAP\Client $client */
$client = Client::account('default');

// Connect to the IMAP server
$client->connect();

// Get all mailboxes
/** @var \Webklex\PHPIMAP\Support\FolderCollection $folders */
$folders = $client->getFolders();
```

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

### Listen for MessageNewEvent

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

Example of listening for MessageNewEvent in AppServiceProvider::boot(). The event's message property is accessed and logged.

```php
<?php

// AppServiceProvider::boot()
use Illuminate\Support\Facades\Event;
use Webklex\IMAP\Events\MessageNewEvent;

Event::listen(MessageNewEvent::class, function (MessageNewEvent $event) {
    // $event->message is the affected \Webklex\PHPIMAP\Message
    \Illuminate\Support\Facades\Log::info('New message: ' . $event->message->subject);
});
```

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

### Dispatch FlagNewEvent example

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

Shows how to manually dispatch an event with arguments. The arguments are packed into an array and passed to the constructor.

```php
FlagNewEvent::dispatch($message, 'seen');
```

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

### Dispatch MessageNewEvent manually

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

Example of dispatching MessageNewEvent manually. The message argument is packed into an array and passed to the constructor.

```php
<?php

use Webklex\IMAP\Events\MessageNewEvent;

// The message argument is packed into an array and passed to the constructor
MessageNewEvent::dispatch($message);
```

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

### boot()

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Registers the package configuration file as publishable. Running the artisan vendor:publish command copies the config file to the application's config directory.

```APIDOC
## boot()

### Description
Registers the package config file `src/config/imap.php` as publishable. Running `php artisan vendor:publish --provider="Webklex\IMAP\Providers\LaravelServiceProvider"` copies it to `config_path('imap.php')`.

### Method
boot

### Endpoint
N/A (PHP method)

### Parameters
None

### Return Type
void

### Example
```php
public function boot() {
    $this->publishes([
        __DIR__ . '/../config/imap.php' => config_path('imap.php'),
    ]);
}
```
```

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

### boot() method - publish config

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Registers the package config file as publishable. Running `php artisan vendor:publish --provider="Webklex\IMAP\Providers\LaravelServiceProvider"` copies it to `config_path('imap.php')`.

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

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

### Usage with Inline Options and Error Handling

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/client-facade.md

Builds a client from an inline configuration array without a named account, then connects inside a try-catch for ConnectionFailedException. Missing options fall back to the default account's configuration.

```php
<?php

use Webklex\IMAP\Facades\Client;
use Webklex\PHPIMAP\Exceptions\ConnectionFailedException;

// Build a client from an inline configuration (no named account needed)
$client = Client::make([
    'host'       => 'imap.example.com',
    'port'       => 993,
    'protocol'   => 'imap',
    'encryption' => 'ssl',
    'username'   => 'user@example.com',
    'password'   => 'secret',
]);

try {
    $client->connect();
} catch (ConnectionFailedException $e) {
    // Handle unreachable / refused connections here
    report($e);
}
```

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

### Client::make($options = [])

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/client-facade.md

Creates a client directly from an inline options array without requiring a named account in config('imap.accounts'). Missing keys fall back to the default account's configuration.

```APIDOC
## Client::make($options = [])

### Description
Creates a client directly from an inline options array without requiring a named account in `config('imap.accounts')`. Missing keys fall back to the default account's configuration.

### Method
Static method on the `Client` facade.

### Parameters
- `$options` (array) - Optional - A full or partial account configuration array, e.g. `['host' => 'imap.example.com', 'port' => 993, ...]`. Missing keys fall back to the default account's configuration.

### Return Type
`\Webklex\PHPIMAP\Client` — a client instance built from the inline account options.

### Usage Example
```php
use Webklex\IMAP\Facades\Client;

$client = Client::make([
    'host'       => 'imap.example.com',
    'port'       => 993,
    'protocol'   => 'imap',
    'encryption' => 'ssl',
    'username'   => 'user@example.com',
    'password'   => 'secret',
]);

try {
    $client->connect();
} catch (ConnectionFailedException $e) {
    report($e);
}
```
```

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

### IMAP Configuration and Client Access

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/configuration.md

Shows the published config/imap.php structure with environment variable overrides and how to access the default account via the Client facade. The config includes host, port, protocol, encryption, certificate validation, credentials, and authentication options.

```php
<?php
// config/imap.php (published)
return [
    'default' => env('IMAP_DEFAULT_ACCOUNT', 'default'),
    'date_format' => 'd-M-Y',
    'accounts' => [
        'default' => [
            'host' => env('IMAP_HOST', 'localhost'),
            'port' => env('IMAP_PORT', 993),
            'protocol' => env('IMAP_PROTOCOL', 'imap'),
            'encryption' => env('IMAP_ENCRYPTION', 'ssl'),
            'validate_cert' => env('IMAP_VALIDATE_CERT', true),
            'username' => env('IMAP_USERNAME', 'root@example.com'),
            'password' => env('IMAP_PASSWORD', ''),
            'authentication' => env('IMAP_AUTHENTICATION', null),
        ],
    ],
    // ... options, decoding, flags, events, masks
];

// Access in application code
$account = config('imap.accounts.default');
$client = Webklex\IMAP\Facades\Client::account('default');
```

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

### handle() method for IMAP idle command

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Executes the command in four steps: resolve the client (using ClientFacade::make() for array accounts or ClientFacade::account() for named accounts), connect, fetch the folder, and run the idle loop. Returns 0 on success, 1 on any failure, logging errors via Log::error().

```php
public function handle() {
    if (is_array($this->account)) {
        $client = ClientFacade::make($this->account);
    }else{
        $client = ClientFacade::account($this->account);
    }

    try {
        $client->connect();
    } catch (ConnectionFailedException $e) {
        Log::error($e->getMessage());
        return 1;
    }

    /** @var Folder $folder */
    try {
        $folder = $client->getFolder($this->folder_name);
    } catch (ConnectionFailedException $e) {
        Log::error($e->getMessage());
        return 1;
    } catch (FolderFetchingException $e) {
        Log::error($e->getMessage());
        return 1;
    }

    try {
        $folder->idle(function($message){
            $this->onNewMessage($message);
        });
    } catch (\Exception $e) {
        Log::error($e->getMessage());
        return 1;
    }

    return 0;
}
```

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

### handle()

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Executes the command in four steps: resolve the client, connect, fetch the folder, and run the idle loop. Returns process exit status: 0 on success, 1 on any failure.

```APIDOC
## handle()

### Description
Executes the command in four steps:
1. **Resolve the client** — if `$account` is an `array`, `ClientFacade::make($this->account)` is used; otherwise `ClientFacade::account($this->account)`.
2. **Connect** — `$client->connect()`; on `ConnectionFailedException` the message is written to the default log channel via `Log::error()` and `1` is returned.
3. **Fetch the folder** — `$client->getFolder($this->folder_name)`; on `ConnectionFailedException` or `FolderFetchingException` the message is logged and `1` is returned.
4. **Run the idle loop** — `$folder->idle(...)` with a closure that forwards each message to `onNewMessage()`. Any `\Exception` is logged and `1` is returned.

### Method
Method

### Parameters
None

### Return Type
`int` — process exit status: `0` on success, `1` on any failure.

### Example
```php
public function handle() {
    if (is_array($this->account)) {
        $client = ClientFacade::make($this->account);
    }else{
        $client = ClientFacade::account($this->account);
    }

    try {
        $client->connect();
    } catch (ConnectionFailedException $e) {
        Log::error($e->getMessage());
        return 1;
    }

    /** @var Folder $folder */
    try {
        $folder = $client->getFolder($this->folder_name);
    } catch (ConnectionFailedException $e) {
        Log::error($e->getMessage());
        return 1;
    } catch (FolderFetchingException $e) {
        Log::error($e->getMessage());
        return 1;
    }

    try {
        $folder->idle(function($message){
            $this->onNewMessage($message);
        });
    } catch (\Exception $e) {
        Log::error($e->getMessage());
        return 1;
    }

    return 0;
}
```
```

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

### Catch connection and folder exceptions around the command's connection path

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/errors.md

Wrap Client::connect() and Client::getFolder() in try/catch blocks to handle ConnectionFailedException and FolderFetchingException. Use this when building consumer code that calls the IMAP client directly. The comments indicate typical causes: wrong host/port, certificate validation failure, network down, connection dropped, or folder does not exist.

```php
<?php

use Webklex\IMAP\Facades\Client;
use Webklex\PHPIMAP\Exceptions\ConnectionFailedException;
use Webklex\PHPIMAP\Exceptions\FolderFetchingException;

$client = Client::account('default');

try {
    $client->connect();
} catch (ConnectionFailedException $e) {
    // e.g. wrong host/port, certificate validation failure, network down
    report($e);
}

try {
    $folder = $client->getFolder('INBOX');
} catch (ConnectionFailedException $e) {
    // connection dropped while selecting the folder
    report($e);
} catch (FolderFetchingException $e) {
    // folder does not exist or could not be listed
    report($e);
}
```

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

### register() method - register singletons

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Merges vendor config and registers `ClientManager` and `Client` as singletons. `Client` resolves to the default-account client via `$app[ClientManager::class]->account()`.

```php
public function register() {
    $this->setVendorConfig();

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

    $this->app->singleton(Client::class, function($app) {
        return $app[ClientManager::class]->account();
    });
}
```

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

### Client Facade Class Definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/client-facade.md

The Client facade extends Illuminate\Support\Facades\Facade and proxies static calls to the Webklex\PHPIMAP\ClientManager singleton. It declares only getFacadeAccessor() and uses Laravel's facade magic for other methods.

```php
<?php

namespace Webklex\IMAP\Facades;

use Illuminate\Support\Facades\Facade;
use Webklex\PHPIMAP\ClientManager;

/**
 * Class Client
 *
 * @package Webklex\IMAP\Facades
 *
 * @method static \Webklex\PHPIMAP\Client account($name = null)
 * @method static \Webklex\PHPIMAP\Client make($options = [])
 */
class Client extends Facade {

    /**
     * Get the registered name of the component.
     *
     * @return string
     */
    protected static function getFacadeAccessor() {
        return ClientManager::class;
    }
}
```

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

### setVendorConfig() - Load and merge vendor config with account inheritance

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Loads the vendor src/config/imap.php as base config and recursively merges it with the user's local imap config. Applies account inheritance: default account settings become fallback for all other accounts unless imap.default is boolean false. Returns void.

```php
private function setVendorConfig() {
    $config_key = 'imap';
    $path = __DIR__ . '/../config/' . $config_key . '.php';

    $vendor_config = require $path;
    $config = $this->app['config']->get($config_key, []);

    $this->app['config']->set($config_key, $this->array_merge_recursive_distinct($vendor_config, $config));

    $config = $this->app['config']->get($config_key);

    if (is_array($config)) {
        if (isset($config['default'])) {
            if (isset($config['accounts']) && $config['default'] != false) {

                $default_config = $vendor_config['accounts']['default'];
                if (isset($config['accounts'][$config['default']])) {
                    $default_config = array_merge($default_config, $config['accounts'][$config['default']]);
                }

                if (is_array($config['accounts'])) {
                    foreach ($config['accounts'] as $account_key => $account) {
                        $config['accounts'][$account_key] = array_merge($default_config, $account);
                    }
                }
            }
        }
    }

    $this->app['config']->set($config_key, $config);
}
```

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

### register()

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Merges the vendor configuration into the application config and registers two singletons in the container: ClientManager and Client. The Client singleton resolves to the default account client.

```APIDOC
## register()

### Description
Merges the vendor config into the application config, then registers `Webklex\PHPIMAP\ClientManager` and `Webklex\PHPIMAP\Client` as singletons in the container. The `Client` singleton is resolved from the default account client.

### Method
register

### Endpoint
N/A (PHP method)

### Parameters
None

### Return Type
void

### Example
```php
public function register() {
    $this->setVendorConfig();

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

    $this->app->singleton(Client::class, function($app) {
        return $app[ClientManager::class]->account();
    });
}
```
```

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

### Client::account($name = null)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/client-facade.md

Resolves the named account configuration from config('imap.accounts') and returns a configured Webklex\PHPIMAP\Client instance. When $name is null, the default account is used.

```APIDOC
## Client::account($name = null)

### Description
Resolves the named account configuration from `config('imap.accounts')` and returns a configured `Webklex\PHPIMAP\Client` instance. When `$name` is `null`, the default account (`config('imap.default')`) is used.

### Method
Static method on the `Client` facade.

### Parameters
- `$name` (string|null) - Optional - The account identifier as configured under `config('imap.accounts')`. When `null`, the default account is used.

### Return Type
`\Webklex\PHPIMAP\Client` — a configured (but not yet connected) IMAP client instance for the named account.

### Usage Example
```php
use Webklex\IMAP\Facades\Client;

$client = Client::account('default');
$client->connect();
$folders = $client->getFolders();
```
```

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

### Listen to folder events

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Registers listeners for FolderNewEvent and FolderMovedEvent in AppServiceProvider::boot(), logging folder creation and move details.

```php
<?php

// AppServiceProvider::boot()
use Illuminate\Support\Facades\Event;
use Webklex\IMAP\Events\FolderNewEvent;
use Webklex\IMAP\Events\FolderMovedEvent;

Event::listen(FolderNewEvent::class, function (FolderNewEvent $event) {
    \Illuminate\Support\Facades\Log::info('Folder created: ' . $event->folder->name);
});

Event::listen(FolderMovedEvent::class, function (FolderMovedEvent $event) {
    \Illuminate\Support\Facades\Log::info(
        "Folder moved from {$event->old_folder->full_name} to {$event->new_folder->full_name}"
    );
});
```

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

### dispatch() method

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

Static method that instantiates the calling event class with variadic arguments packed into an array and passes it to Laravel's global event() helper.

```php
public static function dispatch() {
    return event(new static(func_get_args()));
}
```

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

### __construct()

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Constructor for the IMAP idle command. Calls the parent Illuminate\Console\Command constructor, which compiles the $signature property into the command definition in Laravel 8+.

```APIDOC
## __construct()

### Description
Calls the parent `Illuminate\Console\Command` constructor. In Laravel 8+, the `$signature` property is compiled into the command definition during construction.

### Method
Constructor

### Parameters
None

### Return Type
`void`

### Example
```php
public function __construct() {
    parent::__construct();
}
```
```

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

### Run the idle loop with php artisan imap:idle

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Executes the idle loop, which blocks and streams new messages. The command runs until an exception occurs or the loop completes.

```bash
# Run the idle loop (blocks and streams new messages)
php artisan imap:idle
```

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

### Run imap:idle command and inspect exit status

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/errors.md

Use Artisan::call('imap:idle') to run the command programmatically. The exit code is 0 on success and 1 on any logged failure, as documented in the exit codes table.

```php
<?php

$exitCode = Artisan::call('imap:idle');
// $exitCode === 0 on success, === 1 on any logged failure
```

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

### Event::dispatch()

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

Static helper to dispatch an event through Laravel's global event dispatcher. It instantiates the calling event class with the provided arguments packed into an array and passes it to the event() helper.

```APIDOC
## Event::dispatch()

### Description
Static helper to dispatch an event through Laravel's global event dispatcher. It instantiates the calling event class with the provided arguments packed into an array and passes it to the event() helper.

### Method
Static method

### Signature
```php
public static function dispatch()
```

### Parameters
- **variadic** (mixed) - Optional - Arbitrary arguments forwarded to the event constructor as a positional array.

### Return Type
`void|array` - Whatever Laravel's global `event()` helper returns (the return value of any listener that returns a value, or `null` when no listener returns one).

### Description
Instantiates `new static(func_get_args())` — i.e. the calling event class is constructed with the variadic arguments packed into an array — and passes it to Laravel's global `event()` helper, which dispatches it through the application's event dispatcher.

### Usage Example
```php
MessageNewEvent::dispatch($message);
```
```

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

### Constructor for IMAP Idle Command

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Calls the parent Illuminate\Console\Command constructor. In Laravel 8+, the $signature property is compiled into the command definition during construction.

```php
public function __construct() {
    parent::__construct();
}
```

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

### Class Hierarchy of Folder Events

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Shows the inheritance structure of folder events: FolderNewEvent and FolderMovedEvent extend Event, while FolderDeletedEvent extends FolderNewEvent.

```text
Event (abstract)
├── FolderNewEvent            → $folder
│   └── FolderDeletedEvent    → $folder
└── FolderMovedEvent          → $old_folder, $new_folder
```

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

### IMAP Config Array Structure

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/types.md

Shows the structural shape of the 'imap' config array consumed by ClientManager. The complete key layout with defaults is documented in configuration.md.

```php
[
    'default'     => 'default',            // default account identifier
    'date_format' => 'd-M-Y',
    'accounts'    => ['default' => [ ... account fields ... ]],
    'options'     => [ ... fetch/decode options ... ],
    'decoding'    => [ 'options' => [...], 'decoder' => [...] ],
    'flags'       => ['recent', 'flagged', 'answered', 'deleted', 'seen', 'draft'],
    'events'      => [ 'message' => [...], 'folder' => [...], 'flag' => [...] ],
    'masks'       => [ 'message' => MessageMask::class, 'attachment' => AttachmentMask::class ],
]
```

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

### Listen to flag events

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/flag-events.md

Registers event listeners for FlagNewEvent and FlagDeletedEvent in AppServiceProvider::boot(). Logs the flag name and message UID when a flag is set or removed.

```php
<?php

// AppServiceProvider::boot()
use Illuminate\Support\Facades\Event;
use Webklex\IMAP\Events\FlagNewEvent;
use Webklex\IMAP\Events\FlagDeletedEvent;

Event::listen(FlagNewEvent::class, function (FlagNewEvent $event) {
    \Illuminate\Support\Facades\Log::info(
        "Flag '{$event->flag}' set on message {$event->message->getUid()}"
    );
});

Event::listen(FlagDeletedEvent::class, function (FlagDeletedEvent $event) {
    \Illuminate\Support\Facades\Log::info(
        "Flag '{$event->flag}' removed from message {$event->message->getUid()}"
    );
});
```

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

### Dispatch a folder event manually

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Manually fires a FolderDeletedEvent using the dispatch method, passing a folder instance.

```php
<?php

use Webklex\IMAP\Events\FolderDeletedEvent;

// Manually fire a folder deletion event
FolderDeletedEvent::dispatch($folder);
```

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

### Listen to all message events

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Registers event listeners for MessageNewEvent and MessageMovedEvent in AppServiceProvider::boot(). Logs the subject of new messages and the folder change for moved messages.

```php
<?php

// AppServiceProvider::boot()
use Illuminate\Support\Facades\Event;
use Webklex\IMAP\Events\MessageNewEvent;
use Webklex\IMAP\Events\MessageMovedEvent;

Event::listen(MessageNewEvent::class, function (MessageNewEvent $event) {
    \Illuminate\Support\Facades\Log::info('Mail arrived: ' . $event->message->getSubject());
});

Event::listen(MessageMovedEvent::class, function (MessageMovedEvent $event) {
    \Illuminate\Support\Facades\Log::info(
        "Mail moved from {$event->old_message->getFolder()} to {$event->new_message->getFolder()}"
    );
});
```

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

### FolderNewEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Defines the FolderNewEvent class with a public $folder property and a constructor that assigns the first element of the $folders array to $folder. Fired when a new folder is created.

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Folder;

class FolderNewEvent extends Event {

    /** @var Folder $folder */
    public $folder;

    /**
     * Create a new event instance.
     * @var Folder[] $folders
     * @return void
     */
    public function __construct($folders) {
        $this->folder = $folders[0];
    }
}
```

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

### ImapIdleCommand class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Full implementation of the Laravel Artisan command `imap:idle`. It connects to an IMAP account, selects the INBOX folder, and uses the IDLE extension to invoke `onNewMessage()` for each new message. The command returns 1 on connection, folder, or idle errors, and 0 on success.

```php
<?php

namespace Webklex\IMAP\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Log;
use Webklex\IMAP\Facades\Client as ClientFacade;
use Webklex\PHPIMAP\Exceptions\ConnectionFailedException;
use Webklex\PHPIMAP\Exceptions\FolderFetchingException;
use Webklex\PHPIMAP\Folder;
use Webklex\PHPIMAP\Message;

class ImapIdleCommand extends Command {

    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'imap:idle';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Fetch new messages by utilising imap idle';

    /**
     * Holds the account information
     *
     * @var string|array $account
     */
    protected $account = "default";

    /**
     * Name of the used folder
     *
     * @var string $folder_name
     */
    protected $folder_name = "INBOX";

    /**
     * Create a new command instance.
     *
     * @return void
     */
    public function __construct() {
        parent::__construct();
    }

    /**
     * Callback used for the idle command and triggered for every new received message
     * @param Message $message
     */
    public function onNewMessage(Message $message){
        $this->info("New message received: ".$message->subject);
    }

    /**
     * Execute the console command.
     *
     * @return int
     */
    public function handle() {
        if (is_array($this->account)) {
            $client = ClientFacade::make($this->account);
        }else{
            $client = ClientFacade::account($this->account);
        }

        try {
            $client->connect();
        } catch (ConnectionFailedException $e) {
            Log::error($e->getMessage());
            return 1;
        }

        /** @var Folder $folder */
        try {
            $folder = $client->getFolder($this->folder_name);
        } catch (ConnectionFailedException $e) {
            Log::error($e->getMessage());
            return 1;
        } catch (FolderFetchingException $e) {
            Log::error($e->getMessage());
            return 1;
        }

        try {
            $folder->idle(function($message){
                $this->onNewMessage($message);
            });
        } catch (\Exception $e) {
            Log::error($e->getMessage());
            return 1;
        }

        return 0;
    }
}
```

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

### Abstract Event class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/event-base.md

The abstract base class for all package events. Provides the static dispatch() helper that fires events through Laravel's global event dispatcher.

```php
<?php

namespace Webklex\IMAP\Events;


abstract class Event {

    /**
     * Dispatch the event with the given arguments.
     *
     * @return void|array
     */
    public static function dispatch() {
        return event(new static(func_get_args()));
    }
}
```

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

### onNewMessage(Message $message)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Callback triggered for every new message received during the idle loop. The default implementation prints 'New message received: <subject>' to the console via $this->info(). Override this method in a subclass to implement custom handling.

```APIDOC
## onNewMessage(Message $message)

### Description
Callback triggered for every new message received during the idle loop. The default implementation prints `New message received: <subject>` to the console via `$this->info()`. Override this method in a subclass to implement custom handling.

### Method
Method

### Parameters
- `$message` (\Webklex\PHPIMAP\Message) - Required - The newly received message.

### Return Type
`void`

### Example
```php
public function onNewMessage(Message $message){
    $this->info("New message received: ".$message->subject);
}
```
```

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

### onNewMessage callback for IMAP idle

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Callback triggered for every new message received during the idle loop. The default implementation prints 'New message received: <subject>' to the console via $this->info(). Override this method in a subclass to implement custom handling.

```php
public function onNewMessage(Message $message){
    $this->info("New message received: ".$message->subject);
}
```

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

### FolderNewEvent::__construct($folders)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Constructor for the FolderNewEvent class. Fired when a new folder is created on the server, assigning the first folder from the positional array to the public $folder property.

```APIDOC
## FolderNewEvent::__construct($folders)

### Description
Fired when a new folder is created on the server. The constructor assigns the first element of the positional array to the public `$folder` property.

### Method
Constructor

### Signature
`public function __construct($folders)`

### Parameters
- **$folders** (`\Webklex\PHPIMAP\Folder[]`) - Required - Positional array of arguments passed by `Event::dispatch()`; index `0` is assigned to `$folder`.

### Return Type
`void`

### Public Properties
- **$folder** (`\Webklex\PHPIMAP\Folder`) - The newly created folder.

```

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

### Register LaravelServiceProvider in config/app.php

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Add the service provider to the providers array when auto-discovery is disabled. The commented artisan command publishes the configuration.

```php
<?php

// config/app.php (only needed if auto-discovery is disabled)
'providers' => [
    \Webklex\IMAP\Providers\LaravelServiceProvider::class,
],

// Publish the configuration
// php artisan vendor:publish --provider="Webklex\IMAP\Providers\LaravelServiceProvider"
```

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

### FlagNewEvent::__construct($arguments)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/flag-events.md

Constructor for the FlagNewEvent class. It initializes the event with the affected message and flag name from the provided arguments array.

```APIDOC
## FlagNewEvent::__construct($arguments)

### Description
Constructor for the FlagNewEvent class. It initializes the event with the affected message and flag name from the provided arguments array.

### Method
Constructor

### Parameters
- `$arguments` (mixed[]) - Required - Positional array of arguments passed by `Event::dispatch()`; index `0` → `$message`, index `1` → `$flag`.

### Return Type
void

### Usage Example
```php
FlagNewEvent::dispatch($message, 'seen');
```
```

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

### MessageNewEvent class implementation

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Defines the MessageNewEvent class in the Webklex\IMAP\Events namespace. The constructor accepts a positional array of Message objects and assigns the first element to the public $message property. This event is fired when a new message arrives or is created on the server.

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Message;

class MessageNewEvent extends Event {

    /** @var Message $message */
    public $message;

    /**
     * Create a new event instance.
     * @var Message[] $messages
     * @return void
     */
    public function __construct($messages) {
        $this->message = $messages[0];
    }
}
```

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

### Custom NotifyIdleCommand subclass overriding onNewMessage

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/imap-idle-command.md

Register a custom subclass of ImapIdleCommand to override the callback. Set the account and folder_name properties to target a named account from config('imap.accounts') and a folder to idle on. The onNewMessage method fires an event instead of printing.

```php
<?php

// console.php (register a custom subclass to override the callback)

use Webklex\IMAP\Commands\ImapIdleCommand;
use Webklex\PHPIMAP\Message;

class NotifyIdleCommand extends ImapIdleCommand
{
    protected $account = 'support';     // named account from config('imap.accounts')
    protected $folder_name = 'INBOX';   // folder to idle on

    public function onNewMessage(Message $message)
    {
        // Notify on every new message instead of printing
        event(new \App\Events\MailArrived($message));
    }
}
```

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

### MessageNewEvent::__construct($messages)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Constructs a new MessageNewEvent instance. This event is fired when a new message arrives or is created on the server, and it exposes the affected message via the public $message property.

```APIDOC
## MessageNewEvent::__construct($messages)

### Description
Constructs a new MessageNewEvent instance. This event is fired when a new message arrives or is created on the server, and it exposes the affected message via the public $message property.

### Method
Constructor

### Signature
`public function __construct($messages)`

### Parameters
- **$messages** (\Webklex\PHPIMAP\Message[]) - Required - Positional array of arguments passed by `Event::dispatch()`; index `0` is assigned to `$message`.

### Return Type
`void`

### Public Properties
- **$message** (\Webklex\PHPIMAP\Message) - The newly created message.

```

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

### Class Hierarchy of Message Events

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Shows the inheritance and property relationships among the message event classes. The abstract Event base class is extended by MessageNewEvent, which is extended by MessageDeletedEvent and MessageRestoredEvent, and by MessageMovedEvent, which is extended by MessageCopiedEvent.

```text
Event (abstract)
├── MessageNewEvent            → $message
│   ├── MessageDeletedEvent    → $message
│   └── MessageRestoredEvent   → $message
└── MessageMovedEvent          → $old_message, $new_message
    └── MessageCopiedEvent     → $old_message, $new_message
```

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

### FlagNewEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/flag-events.md

Defines the FlagNewEvent class with public $message and $flag properties. The constructor takes a positional array of arguments where index 0 is the message and index 1 is the flag. Fired when a new flag is set on a message.

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Message;

class FlagNewEvent extends Event {

    /** @var Message $message */
    public $message;

    /** @var string $flag */
    public $flag;

    /**
     * Create a new event instance.
     * @var mixed[] $arguments
     * @return void
     */
    public function __construct($arguments) {
        $this->message = $arguments[0];
        $this->flag = $arguments[1];
    }
}
```

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

### Dispatch a flag event manually

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/flag-events.md

Manually fires a 'seen' flag event for a message using FlagNewEvent::dispatch(). The dispatch helper packs the message and flag as arguments.

```php
<?php

use Webklex\IMAP\Events\FlagNewEvent;

// Manually fire a "seen" flag event for a message
FlagNewEvent::dispatch($message, 'seen');
```

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

### FlagDeletedEvent::__construct($arguments)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/flag-events.md

Constructor for the FlagDeletedEvent class. Inherits from FlagNewEvent and initializes the event with the affected message and flag name from the provided arguments array.

```APIDOC
## FlagDeletedEvent::__construct($arguments)

### Description
Constructor for the FlagDeletedEvent class. Inherits from FlagNewEvent and initializes the event with the affected message and flag name from the provided arguments array.

### Method
Constructor

### Parameters
- `$arguments` (mixed[]) - Required - Positional array of arguments passed by `Event::dispatch()`; index `0` → `$message`, index `1` → `$flag`.

### Return Type
void

### Usage Example
```php
FlagDeletedEvent::dispatch($message, 'seen');
```
```

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

### FolderDeletedEvent::__construct($folders)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Constructor for the FolderDeletedEvent class, inherited from FolderNewEvent. Fired when a folder is deleted, distinguishing deletion from creation via the event type.

```APIDOC
## FolderDeletedEvent::__construct($folders)

### Description
Fired when a folder is deleted. This event is an empty subclass of `FolderNewEvent`, inheriting the `$folder` property and constructor; the event type itself distinguishes a deletion from a creation.

### Method
Constructor (inherited)

### Signature
`public function __construct($folders)`

### Parameters
- **$folders** (`\Webklex\PHPIMAP\Folder[]`) - Required - Positional array of arguments passed by `Event::dispatch()`; index `0` is assigned to `$folder`.

### Return Type
`void`

### Public Properties
- **$folder** (`\Webklex\PHPIMAP\Folder`) - The deleted folder.

```

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

### FolderMovedEvent::__construct($folders)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Constructor for the FolderMovedEvent class. Fired when a folder is moved or renamed, exposing the folder state before and after the move via public properties.

```APIDOC
## FolderMovedEvent::__construct($folders)

### Description
Fired when a folder is moved/renamed. The constructor assigns the first element to `$old_folder` and the second to `$new_folder` from the positional array.

### Method
Constructor

### Signature
`public function __construct($folders)`

### Parameters
- **$folders** (`\Webklex\PHPIMAP\Folder[]`) - Required - Positional array; index `0` → `$old_folder`, index `1` → `$new_folder`.

### Return Type
`void`

### Public Properties
- **$old_folder** (`\Webklex\PHPIMAP\Folder`) - The folder before the move.
- **$new_folder** (`\Webklex\PHPIMAP\Folder`) - The folder after the move.

```

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

### MessageCopiedEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Empty subclass of MessageMovedEvent. Inherits $old_message / $new_message properties and constructor. Fired when a message is copied (source remains in place, destination receives a copy).

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Message;

class MessageCopiedEvent extends MessageMovedEvent {

}
```

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

### FolderMovedEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Defines the FolderMovedEvent class with public $old_folder and $new_folder properties, assigned from the first two elements of the $folders array. Fired when a folder is moved or renamed.

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Folder;

class FolderMovedEvent extends Event {

    /** @var Folder $old_folder */
    public $old_folder;
    /** @var Folder $new_folder */
    public $new_folder;

    /**
     * Create a new event instance.
     * @var Folder[] $folders
     * @return void
     */
    public function __construct($folders) {
        $this->old_folder = $folders[0];
        $this->new_folder = $folders[1];
    }
}
```

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

### MessageMovedEvent::__construct($messages)

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Event fired when a message is moved from one folder to another. Exposes the message state before and after the move.

```APIDOC
## MessageMovedEvent::__construct($messages)

### Description
Event fired when a message is moved from one folder to another. Exposes the message state before and after the move.

### Constructor
`__construct($messages)`

### Parameters
- `$messages` (\Webklex\PHPIMAP\Message[]) - Required - Positional array; index `0` → `$old_message`, index `1` → `$new_message`.

### Return Type
`void`

### Public Properties
- `$old_message` (\Webklex\PHPIMAP\Message) - The message before the move.
- `$new_message` (\Webklex\PHPIMAP\Message) - The message after the move.

```

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

### MessageMovedEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Event fired when a message is moved from one folder to another. Exposes the message state before and after the move via $old_message and $new_message properties. Constructor accepts a positional array of two Message objects.

```php
<?php

namespace Webklex\IMAP\Events;

use Webklex\PHPIMAP\Message;

class MessageMovedEvent extends Event {

    /** @var Message $old_message */
    public $old_message;
    /** @var Message $new_message */
    public $new_message;

    /**
     * Create a new event instance.
     * @var Message[] $messages
     * @return void
     */
    public function __construct($messages) {
        $this->old_message = $messages[0];
        $this->new_message = $messages[1];
    }
}
```

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

### array_merge_recursive_distinct() - Recursively merge arrays with unique numeric keys

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/laravel-service-provider.md

Recursively merges any number of arrays. String keys are replaced by later values; numeric keys are appended only when unique. Used internally by setVendorConfig(). Returns array|mixed.

```php
private function array_merge_recursive_distinct() {
    $arrays = func_get_args();
    $base = array_shift($arrays);

    if (!is_array($base)) $base = empty($base) ? array() : array($base);

    foreach ($arrays as $append) {

        if (!is_array($append)) $append = array($append);

        foreach ($append as $key => $value) {

            if (!array_key_exists($key, $base) and !is_numeric($key)) {
                $base[$key] = $append[$key];
                continue;
            }

            if (is_array($value) or is_array($base[$key])) {
                $base[$key] = $this->array_merge_recursive_distinct($base[$key], $append[$key]);
            } else if (is_numeric($key)) {
                if (!in_array($value, $base)) $base[] = $value;
            } else {
                $base[$key] = $value;
            }

        }

    }

    return $base;
}
```

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

### Dispatch a message event manually

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Manually fires a MessageDeletedEvent for a message using the dispatch() helper.

```php
<?php

use Webklex\IMAP\Events\MessageDeletedEvent;

// Manually fire a deletion event for a message
MessageDeletedEvent::dispatch($message);
```

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

### FolderDeletedEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/folder-events.md

Empty subclass of FolderNewEvent that inherits the $folder property and constructor. The event type distinguishes a deletion from a creation.

```php
<?php

namespace Webklex\IMAP\Events;

class FolderDeletedEvent extends FolderNewEvent {

}
```

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

### MessageRestoredEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Empty subclass of MessageNewEvent. Inherits the $message property and constructor. Fired when a previously deleted (but not expunged) message is restored.

```php
<?php

namespace Webklex\IMAP\Events;


class MessageRestoredEvent extends MessageNewEvent {

}
```

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

### MessageDeletedEvent class definition

Source: https://github.com/webklex/laravel-imap/blob/master/_autodocs/api-reference/message-events.md

Empty subclass of MessageNewEvent. Inherits the $message property and constructor; the event type distinguishes deletion from creation. Fired when a message is deleted.

```php
<?php

namespace Webklex\IMAP\Events;


class MessageDeletedEvent extends MessageNewEvent {

}
```
Tokens:
Raw