PHP-IMAP

https://github.com/webklex/php-imap
Admin
PHP-IMAP is a wrapper for IMAP communication that works without requiring the php-imap module to be...
Tokens:15,369
Snippets:160
Trust Score:8.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PHP-IMAP package

Source: https://github.com/webklex/php-imap/wiki/Installation

Installs the PHP-IMAP package via Composer. Run after installing the decoding modules.

```shell
composer require webklex/php-imap
```

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

### Basic usage example

Source: https://github.com/webklex/php-imap/wiki/Basic-usage-example

This example connects to an IMAP server, retrieves all folders, and iterates through messages to display subject, attachments, and HTML body, then moves each message to 'INBOX.read'.

```php
use Webklex\PHPIMAP\ClientManager;
use Webklex\PHPIMAP\Client;

$cm = new ClientManager('path/to/config/imap.php');

// or use an array of options instead
$cm = new ClientManager($options = []);

/** @var \Webklex\PHPIMAP\Client $client */
$client = $cm->account('account_identifier');

// or create a new instance manually        
$client = $cm->make([
    'host'          => 'localhost',
    'port'          => 993,
    'encryption'    => 'ssl',
    'validate_cert' => true,
    'username'      => 'username',
    'password'      => 'password',
    'protocol'      => 'imap'
]);

//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->moveToFolder('INBOX.read') == true){
            echo 'Message has ben moved';
        }else{
            echo 'Message could not be moved';
        }
    }
}
```

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

### Install php-imap module (optional)

Source: https://github.com/webklex/php-imap/wiki/Installation

Optionally installs the php-imap module if encoding problems occur. Restarts Apache after installation.

```shell
sudo apt-get install php*-imap && sudo apache2ctl graceful
```

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

### Install decoding modules

Source: https://github.com/webklex/php-imap/wiki/Installation

Installs the mbstring and mcrypt PHP extensions and restarts Apache. Required before installing the PHP-IMAP package.

```shell
sudo apt-get install php*-mbstring php*-mcrypt && sudo apache2ctl graceful
```

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

### Connect to IMAP and process messages with Webklex\PHPIMAP\ClientManager

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

Basic example that connects to an IMAP account, retrieves all folders, iterates through messages, prints subject, attachment count, and HTML body, and moves each message to 'INBOX.read'. Requires a configuration file at 'path/to/config/imap.php' and an account identifier. This example is not intended for production use.

```php
use Webklex\PHPIMAP\ClientManager;

require_once "vendor/autoload.php";

$cm = new ClientManager('path/to/config/imap.php');

/** @var \Webklex\PHPIMAP\Client $client */
$client = $cm->account('account_identifier');

//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';
        }
    }
}
```

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

### Run Docker test container

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

Start the IMAP server container with port 993 mapped to the host.

```bash
docker run --name imap-server -p 993:993 --rm -d php-imap-server
```

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

### mask

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get a masked instance.

```APIDOC
## mask

### Description
Get a masked instance.

### Method
N/A

### Endpoint
N/A

### Parameters
- **mask** (string) - Optional - The mask class name.

### Response
- **Return Type**: Mask
- **Description**: A masked instance.
```

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

### Paginated list example with Blade template

Source: https://github.com/webklex/php-imap/wiki/Pagination

Shows how to paginate a search result and render a paginated list in a Blade template, including pagination links.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->search()
->since(\Carbon::now()->subDays(14))->get()
->paginate($perPage = 5, $page = null, $pageName = 'imap_blade_example');
```

```html
<table>
    <thead>
    <tr>
        <th>UID</th>
        <th>Subject</th>
        <th>From</th>
        <th>Attachments</th>
    </tr>
    </thead>
    <tbody>
        <?php if($paginator->count() > 0): ?>
            <?php foreach($paginator as $oMessage): ?>
            <tr>
                <td><?php echo $oMessage->getUid(); ?></td>
                <td><?php echo $oMessage->getSubject(); ?></td>
                <td><?php echo $oMessage->getFrom()[0]->mail; ?></td>
                <td><?php echo $oMessage->getAttachments()->count() > 0 ? 'yes' : 'no'; ?></td>
            </tr>
            <?php endforeach; ?>
        <?php else: ?>
            <tr>
                <td colspan="4">No messages found</td>
            </tr>
        <?php endif; ?>
    </tbody>
</table>

<?php echo $paginator->links(); ?>
```

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

### get

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Fetches messages with the current query.

```APIDOC
## get

### Description
Fetches messages with the current query.

### Method
get

### Arguments
None

### Return
MessageCollection
```

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

### Get a specific folder with getFolder()

Source: https://github.com/webklex/php-imap/wiki/Folder---Mailbox

Fetches a specific folder by its name (e.g., 'INBOX.name'). Returns a Folder object. Requires an existing Client instance.

```php
/** @var \Webklex\PHPIMAP\Client $oClient */

/** @var \Webklex\PHPIMAP\Folder $oFolder */
$oFolder = $oClient->getFolder('INBOX.name');
```

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

### setSize

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment size.

```APIDOC
## setSize

### Description
Get attachment size.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: int or null
- **Description**: The attachment size.
```

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

### Idle with callback to handle new messages

Source: https://github.com/webklex/php-imap/wiki/Idle

Use the idle method on a Folder instance to wait for new messages. The callback receives the new message and can access its properties, such as subject. The example echoes the subject followed by a newline.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */
$oFolder->idle(function($message){
    echo $message->subject."\n";
});
```

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

### getName

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment name.

```APIDOC
## getName

### Description
Get attachment name.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment name.
```

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

### getExtension

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get a guessed attachment extension.

```APIDOC
## getExtension

### Description
Get a guessed attachment extension.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The guessed attachment extension.
```

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

### Search for messages with various criteria

Source: https://github.com/webklex/php-imap/wiki/Search-for-messages

Shows how to retrieve messages using the query() method with different filters: all, from, since, text, unseen, and custom where clauses. Includes experimental notText and custom criteria examples.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

//Get all messages
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->all()->get();

//Get all messages from example@domain.com
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->from('example@domain.com')->get();

//Get all messages since march 15 2018
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->get();

//Get all messages within the last 5 days
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since(now()->subDays(5))->get();
//Or for older laravel versions..
$aMessage = $oFolder->query()->since(\Carbon::now()->subDays(5))->get();

//Get all messages containing "hello world"
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->get();

//Get all unseen messages containing "hello world"
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->unseen()->text('hello world')->get();

//Extended custom search query for all messages containing "hello world" 
//and have been received since march 15 2018
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->since('15.03.2018')->get();
$aMessage = $oFolder->query()->Text('hello world')->Since('15.03.2018')->get();
$aMessage = $oFolder->query()->whereText('hello world')->whereSince('15.03.2018')->get();

// Build a custom search query
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()
->where([['TEXT', 'Hello world'], ['SINCE', \Carbon::parse('15.03.2018')]])
->get();

//!EXPERIMENTAL!
//Get all messages NOT containing "hello world"
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->notText('hello world')->get();
$aMessage = $oFolder->query()->not_text('hello world')->get();
$aMessage = $oFolder->query()->not()->text('hello world')->get();

//Get all messages by custom search criteria
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->where(["CUSTOM_FOOBAR" => "fooBar"]])->get();
```

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

### getContent

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment content.

```APIDOC
## getContent

### Description
Get attachment content.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment content.
```

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

### getType

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment type.

```APIDOC
## getType

### Description
Get attachment type.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment type.
```

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

### getDisposition

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment disposition.

```APIDOC
## getDisposition

### Description
Get attachment disposition.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment disposition.
```

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

### getId

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment id.

```APIDOC
## getId

### Description
Get attachment id.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment id.
```

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

### getMimeType

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment mime type.

```APIDOC
## getMimeType

### Description
Get attachment mime type.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment mime type.
```

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

### Set and unset message flags in PHP

Source: https://github.com/webklex/php-imap/wiki/Message-flags

Use setFlag to apply one or more flags (e.g., 'Seen', 'Spam') to a message, and unsetFlag to remove a flag. The example assumes a Message object instance.

```php
/** @var \Webklex\PHPIMAP\Message $oMessage */
$oMessage->setFlag(['Seen', 'Spam']);
$oMessage->unsetFlag('Spam');
```

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

### getContentType

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get attachment content type.

```APIDOC
## getContentType

### Description
Get attachment content type.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string or null
- **Description**: The attachment content type.
```

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

### Save message attachments with getAttachments() and save()

Source: https://github.com/webklex/php-imap/wiki/Attachments

Retrieves the attachment collection from a message and saves each attachment to the specified directory. The example assumes $oMessage is a Webklex\PHPIMAP\Message instance and uses the each() method to iterate over the collection.

```php
/** @var \Webklex\PHPIMAP\Message $oMessage */

/** @var \Webklex\PHPIMAP\Support\AttachmentCollection $aAttachment */
$aAttachment = $oMessage->getAttachments();

$aAttachment->each(function ($oAttachment) {
    /** @var \Webklex\PHPIMAP\Attachment $oAttachment */
    $oAttachment->save("/some/path/");
});
```

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

### getMask

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Get the current mask class name.

```APIDOC
## getMask

### Description
Get the current mask class name.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Response
- **Return Type**: string
- **Description**: The current mask class name.
```

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

### connect

Source: https://github.com/webklex/php-imap/wiki/Client::class

Establishes a connection to the server.

```APIDOC
## connect

### Description
Connect to server.

### Method
connect

### Parameters
None

### Return
None

```

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

### Build Docker test image

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

Build the IMAP server Docker image from the .github/docker directory.

```bash
cd .github/docker

docker build -t php-imap-server .
```

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

### Run tests via Composer

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

Execute the project test suite using the composer test command.

```bash
composer test
```

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

### List all folders with getFolders()

Source: https://github.com/webklex/php-imap/wiki/Folder---Mailbox

Retrieves all available folders from the IMAP client. The result is a FolderCollection object. Requires an existing Client instance.

```php
/** @var \Webklex\PHPIMAP\Client $oClient */

/** @var \Webklex\PHPIMAP\Support\FolderCollection $aFolder */
$aFolder = $oClient->getFolders();
```

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

### createFolder

Source: https://github.com/webklex/php-imap/wiki/Client::class

Creates a new folder with the given name.

```APIDOC
## createFolder

### Description
Create a new folder.

### Method
createFolder

### Parameters
- **$name** (string) - Required - The name of the new folder.

### Return
- **boolean** - True on success, false on failure.

```

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

### Configure PHPUnit for live mailbox testing

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

Enable live mailbox testing by setting LIVE_MAILBOX to true and providing the necessary IMAP connection details in phpunit.xml.

```xml
<php>
    <env name="LIVE_MAILBOX" value="true"/>
    <env name="LIVE_MAILBOX_DEBUG" value="true"/>
    <env name="LIVE_MAILBOX_HOST" value="mail.example.local"/>
    <env name="LIVE_MAILBOX_PORT" value="993"/>
    <env name="LIVE_MAILBOX_VALIDATE_CERT" value="false"/>
    <env name="LIVE_MAILBOX_QUOTA_SUPPORT" value="true"/>
    <env name="LIVE_MAILBOX_ENCRYPTION" value="ssl"/>
    <env name="LIVE_MAILBOX_USERNAME" value="root@example.local"/>
    <env name="LIVE_MAILBOX_PASSWORD" value="foobar"/>
</php>
```

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

### openFolder

Source: https://github.com/webklex/php-imap/wiki/Client::class

Opens a given folder for operations.

```APIDOC
## openFolder

### Description
Open a given folder.

### Method
openFolder

### Parameters
- **$folder** (string or Folder) - Required - The folder to open.
- **$attempts** (integer) - Optional - Number of attempts.

### Return
None

```

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

### setFetchOptions

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Sets the fetch options.

```APIDOC
## setFetchOptions

### Description
Sets the fetch options.

### Method
setFetchOptions

### Arguments
- **$fetch_options** (boolean) - Required - The fetch options to set.

### Return
WhereQuery
```

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

### setConfig

Source: https://github.com/webklex/php-imap/wiki/Client::class

Sets the client configuration using an array of options, as inspired by the config/imap.php file.

```APIDOC
## setConfig

### Description
Sets the Client configuration. Take a look at `config/imap.php` for more inspiration.

### Method
setConfig

### Parameters
- **$config** (array) - Required - Configuration array.

### Return
- **self** - Returns the Client instance for chaining.

```

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

### getFolder

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves a Folder instance by its name.

```APIDOC
## getFolder

### Description
Get a Folder instance by name.

### Method
getFolder

### Parameters
- **$folder_name** (string) - Required - The name of the folder.
- **$attributes** (int) - Optional - Default 32.
- **$delimiter** (int or null) - Optional - The delimiter.
- **$prefix_address** (bool) - Optional - Whether to prefix the address.

### Return
- **Folder** - The Folder instance.

```

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

### getQuotaRoot

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves the quota settings per user for a given quota root.

```APIDOC
## getQuotaRoot

### Description
Retrieve the quota settings per user.

### Method
getQuotaRoot

### Parameters
- **$quota_root** (string) - Required - The quota root.

### Return
- **array** - Quota settings.

```

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

### Set default message mask via client and message

Source: https://github.com/webklex/php-imap/wiki/Masking

Shows how to set the default message mask using the client's setDefaultMessageMask method and the message's setMask method. The last line generates a masked instance without changing the default.

```php
/** @var \Webklex\PHPIMAP\Client $oClient */
/** @var \Webklex\PHPIMAP\Message $oMessage */

$message_mask = \Webklex\PHPIMAP\Support\Masks\MessageMask::class;

$oClient->setDefaultMessageMask($message_mask);
$oMessage->setMask($message_mask);
$mask = $oMessage->mask($message_mask);
```

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

### since

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages since a given date.

```APIDOC
## since

### Description
Selects messages since a given date.

### Method
since

### Arguments
- **$value** (string) - Required - The date to match.

### Return
WhereQuery
```

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

### checkConnection

Source: https://github.com/webklex/php-imap/wiki/Client::class

Checks if the connection is established and connects if not.

```APIDOC
## checkConnection

### Description
Determine if connection was established and connect if not.

### Method
checkConnection

### Parameters
None

### Return
None

```

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

### Custom MessageNewEvent registration with setEvent

Source: https://github.com/webklex/php-imap/wiki/Events

Create a custom event class extending MessageNewEvent and register it with the client using setEvent. The constructor receives an array of messages and echoes the subject of the first message. Alternatively, set the event in the config file under 'events.message.new'.

```php
class CustomMessageNewEvent extends Webklex\PHPIMAP\Events\MessageNewEvent {

    /**
     * Create a new event instance.
     * @var Message[] $messages
     * @return void
     */
    public function __construct($messages) {
        $this->message = $messages[0];
        echo "New message: ".$this->message->subject."\n";
    }
}

/** @var \Webklex\PHPIMAP\Client $client */
$client->setEvent("message", "new", CustomMessageNewEvent::class);
```

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

### Fetch message by UID using getMessage

Source: https://github.com/webklex/php-imap/wiki/Fetch-a-specific-message

Retrieves a message from a folder by its UID. The UID is not unique and can change, so use with caution.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

/** @var \Webklex\PHPIMAP\Message $oMessage */
$oMessage = $oFolder->query()->getMessage($msgn = 1);
```

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

### on

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages on a given date.

```APIDOC
## on

### Description
Selects messages on a given date.

### Method
on

### Arguments
- **$value** (string) - Required - The date to match.

### Return
WhereQuery
```

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

### save

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Save the attachment content to your filesystem.

```APIDOC
## save

### Description
Save the attachment content to your filesystem.

### Method
N/A

### Endpoint
N/A

### Parameters
- **path** (string) - Required - The path where to save the attachment.
- **filename** (string) - Required - The filename to use for the saved attachment.

### Response
- **Return Type**: boolean
- **Description**: Whether the save operation was successful.
```

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

### Connect to Gmail with an application password using Webklex PHP IMAP

Source: https://github.com/webklex/php-imap/wiki/Google-Mail---Gmail

Use this PHP snippet to connect to Gmail using an application-specific password. Generate the password via Google Account settings (Security > App passwords) and use it without spaces as the 'password' value. The client manager creates a client with the specified IMAP settings and connects.

```php
$cm = new \Webklex\PHPIMAP\Clientmanager();
/** @var \Webklex\PHPIMAP\Client $message */
$client = $cm->make([
   'host'          => 'imap.googlemail.com',
   'port'          => 993,
   'encryption'    => 'ssl',
   'validate_cert' => false,
   'protocol'      => 'imap',
   'username'      => 'username@gmail.com',
   'password'      => 'new-generated-password'
]);
$client->connect();
```

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

### all

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects all available messages.

```APIDOC
## all

### Description
Selects all available messages.

### Method
all

### Arguments
None

### Return
WhereQuery
```

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

### before

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages before a given date.

```APIDOC
## before

### Description
Selects messages before a given date.

### Method
before

### Arguments
- **$value** (string) - Required - The date to match.

### Return
WhereQuery
```

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

### new

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects new messages.

```APIDOC
## new

### Description
Selects new messages.

### Method
new

### Arguments
None

### Return
WhereQuery
```

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

### Connect to Gmail IMAP with OAuth using Clientmanager

Source: https://github.com/webklex/php-imap/wiki/oAuth

Configure a PHP IMAP client to use OAuth authentication with Gmail. Set 'authentication' to "oauth" and provide the host, port, encryption, and credentials. After making the client, call connect() to establish the IMAP connection.

```php
use Webklex\PHPIMAP\Clientmanager;

$cm = new Clientmanager();

/** @var \Webklex\PHPIMAP\Client $client */
$client = $cm->make([
    'host' => 'imap.gmail.com',
    'port' => 993,
    'encryption' => 'ssl',
    'validate_cert' => true,
    'username' => 'example@gmail.com',
    'password' => 'PASSWORD',
    'authentication' => "oauth",
    'protocol' => 'imap'
]);

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

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

### from

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given sender (From:).

```APIDOC
## from

### Description
Selects messages matching a given sender (From:).

### Method
from

### Arguments
- **$value** (string) - Required - The sender address to match.

### Return
WhereQuery
```

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

### Connect to Gmail with OAuth using Webklex PHP IMAP

Source: https://github.com/webklex/php-imap/wiki/Google-Mail---Gmail

Use this PHP snippet to connect to Gmail via OAuth. Set the 'authentication' option to "oauth" and provide the access token as the 'password' value. The client manager creates a client with the specified IMAP settings and connects.

```php
$cm = new \Webklex\PHPIMAP\Clientmanager();
/** @var \Webklex\PHPIMAP\Client $message */
$client = $cm->make([
   'host'           => 'imap.googlemail.com',
   'port'           => 993,
   'encryption'     => 'ssl',
   'validate_cert'  => false,
   'protocol'       => 'imap',
   'username'       => 'username@gmail.com',
   'password'       => 'ACCESS-TOKEN',
   'authentication' => "oauth",
]);
$client->connect();
```

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

### Paginate a query

Source: https://github.com/webklex/php-imap/wiki/Pagination

Paginates the result of a query on a Folder instance. Returns a LengthAwarePaginator.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->query()->since('15.03.2018')->paginate();
```

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

### getFolders

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves the list of folders, optionally as a hierarchical tree.

```APIDOC
## getFolders

### Description
Get folders list. If hierarchical order is set to true, it will make a tree of folders, otherwise it will return flat array.

### Method
getFolders

### Parameters
- **$hierarchical** (bool) - Required - Whether to return a hierarchical tree.
- **$parent_folder** (string or null) - Optional - The parent folder.

### Return
- **FolderCollection** - The collection of folders.

```

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

### Set default attachment mask

Source: https://github.com/webklex/php-imap/wiki/Masking

Shows how to set the default attachment mask using the client's setDefaultAttachmentMask and the attachment's setMask methods. The last line generates a masked instance without changing the default.

```php
/** @var \Webklex\PHPIMAP\Client $oClient */
/** @var \Webklex\PHPIMAP\Attachment $oAttachment */
$attachment_mask = \Webklex\PHPIMAP\Support\Masks\AttachmentMask::class;

$oClient->setDefaultAttachmentMask($attachment_mask);
$oAttachment->setMask($attachment_mask);
$mask = $oAttachment->mask($attachment_mask);
```

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

### Search aliases: search() and messages()

Source: https://github.com/webklex/php-imap/wiki/Search-for-messages

Shows that Folder::search() and Folder::messages() are aliases for Folder::query(), allowing the same search criteria to be used.

```php
// Folder::search() is just an alias for Folder::query()
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->search()->text('hello world')->since('15.03.2018')->get();

// Folder::messages() is just an alias for Folder::query()
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->messages()->text('hello world')->since('15.03.2018')->get();
```

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

### setFetchFlags

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Sets the fetch flags option.

```APIDOC
## setFetchFlags

### Description
Sets the fetch flags option.

### Method
setFetchFlags

### Arguments
- **$fetch_flags** (boolean) - Required - The fetch flags option to set.

### Return
WhereQuery
```

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

### getQuota

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves the quota level settings and usage statistics per mailbox.

```APIDOC
## getQuota

### Description
Retrieve the quota level settings, and usage statics per mailbox.

### Method
getQuota

### Parameters
None

### Return
- **array** - Quota settings and usage.

```

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

### keyword

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given keyword.

```APIDOC
## keyword

### Description
Selects messages matching a given keyword.

### Method
keyword

### Arguments
- **$value** (string) - Required - The keyword to match.

### Return
WhereQuery
```

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

### body

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given HTML body.

```APIDOC
## body

### Description
Selects messages matching a given HTML body.

### Method
body

### Arguments
- **$value** (string) - Required - The HTML body to match.

### Return
WhereQuery
```

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

### isConnected

Source: https://github.com/webklex/php-imap/wiki/Client::class

Determines if a connection to the server has been established.

```APIDOC
## isConnected

### Description
Determine if connection was established.

### Method
isConnected

### Parameters
None

### Return
- **bool** - True if connected, false otherwise.

```

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

### seen

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects seen messages.

```APIDOC
## seen

### Description
Selects seen messages.

### Method
seen

### Arguments
None

### Return
WhereQuery
```

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

### setFetchBody

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Sets the fetch body option.

```APIDOC
## setFetchBody

### Description
Sets the fetch body option.

### Method
setFetchBody

### Arguments
- **$fetch_body** (boolean) - Required - The fetch body option to set.

### Return
WhereQuery
```

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

### Configure PHPUnit for static testing

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

Disable tests requiring a live mailbox by setting the LIVE_MAILBOX environment variable to false in phpunit.xml.

```xml
<php>
    <env name="LIVE_MAILBOX" value="false"/>
</php>
```

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

### flagged

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given flag.

```APIDOC
## flagged

### Description
Selects messages matching a given flag.

### Method
flagged

### Arguments
- **$value** (string) - Required - The flag to match.

### Return
WhereQuery
```

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

### Count all messages and messages since a date

Source: https://github.com/webklex/php-imap/wiki/Counting-messages

Counts all messages in a folder using the query builder's 'all()' method, and counts messages since a specific date using the 'since()' method. The folder object is assumed to be of type \Webklex\PHPIMAP\Folder.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

//Count all messages
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$count = $oFolder->query()->all()->count();

//Count all messages since march 15 2018
$count = $oFolder->query()->since('15.03.2018')->count();
```

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

### text

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given text body.

```APIDOC
## text

### Description
Selects messages matching a given text body.

### Method
text

### Arguments
- **$value** (string) - Required - The text to match.

### Return
WhereQuery
```

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

### Fetch messages without body and flag fetching

Source: https://github.com/webklex/php-imap/wiki/Advanced-fetching

Use setFetchFlags(false) and setFetchBody(false) to disable both flag and body fetching, further reducing load. The query can filter by text or fetch all messages.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')
->setFetchFlags(false)
->setFetchBody(false)
->get();

/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()
->setFetchFlags(false)
->setFetchBody(false)
->get();
```

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

### unkeyword

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given unkeyword.

```APIDOC
## unkeyword

### Description
Selects messages matching a given unkeyword.

### Method
unkeyword

### Arguments
- **$value** (string) - Required - The unkeyword to match.

### Return
WhereQuery
```

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

### subject

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given subject.

```APIDOC
## subject

### Description
Selects messages matching a given subject.

### Method
subject

### Arguments
- **$value** (string) - Required - The subject to match.

### Return
WhereQuery
```

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

### old

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects old messages.

```APIDOC
## old

### Description
Selects old messages.

### Method
old

### Arguments
None

### Return
WhereQuery
```

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

### limit

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Limits the amount of messages being fetched.

```APIDOC
## limit

### Description
Limits the amount of messages being fetched.

### Method
limit

### Arguments
- **$limit** (integer) - Required - The maximum number of messages to fetch.
- **$page** (integer) - Optional - The page number (default: 1).

### Return
WhereQuery
```

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

### getConnection

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves the current IMAP resource connection.

```APIDOC
## getConnection

### Description
Get the current imap resource.

### Method
getConnection

### Parameters
- **$connection** (resource) - Required - The connection resource.

### Return
- **resource** - The current IMAP resource.

```

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

### where

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Adds a new search criterion to the current query.

```APIDOC
## where

### Description
Add new criteria to the current query.

### Method
where

### Arguments
- **$criteria** (mixed) - Required - The criteria to add.
- **$value** (mixed) - Optional - The value for the criteria.

### Return
WhereQuery
```

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

### Call default mask on a message

Source: https://github.com/webklex/php-imap/wiki/Masking

Calls the mask method without arguments to apply the default message mask. The masked instance is returned and can be used to access custom functionality.

```php
/** @var \Webklex\PHPIMAP\Message $oMessage */
$mask = $oMessage->mask();
```

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

### Create and use a custom message mask

Source: https://github.com/webklex/php-imap/wiki/Masking

Extends MessageMask to add a custom token method that combines message_id, uid, and message_no. The mask is applied to a message and the custom method is called.

```php
/** @var \Webklex\PHPIMAP\Message $oMessage */
class CustomMessageMask extends \Webklex\PHPIMAP\Support\Masks\MessageMask {

    /**
     * New custom method which can be called through a mask
     * @return string
     */
    public function token(){
        return implode('-', [$this->message_id, $this->uid, $this->message_no]);
    }
}

$mask = $oMessage->mask(CustomMessageMask::class);

echo $mask->token().'@'.$mask->uid;
```

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

### reconnect

Source: https://github.com/webklex/php-imap/wiki/Client::class

Terminates the current connection and reconnects to the server.

```APIDOC
## reconnect

### Description
Terminate and reconnect to server.

### Method
reconnect

### Parameters
None

### Return
None

```

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

### to

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given receiver (To:).

```APIDOC
## to

### Description
Selects messages matching a given receiver (To:).

### Method
to

### Arguments
- **$value** (string) - Required - The receiver address to match.

### Return
WhereQuery
```

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

### andWhere

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Adds an AND condition to the query using a closure.

```APIDOC
## andWhere

### Description
If supported, performs an extended search request using an AND condition.

### Method
andWhere

### Arguments
- **$closure** (Closure) - Required - The closure defining the AND condition.

### Return
WhereQuery
```

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

### Stop Docker test container

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

Stop the running IMAP server container.

```bash
docker stop imap-server
```

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

### recent

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects recent messages.

```APIDOC
## recent

### Description
Selects recent messages.

### Method
recent

### Arguments
None

### Return
WhereQuery
```

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

### unflagged

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects unflagged messages.

```APIDOC
## unflagged

### Description
Selects unflagged messages.

### Method
unflagged

### Arguments
None

### Return
WhereQuery
```

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

### markAsRead

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Marks all messages as read during fetching.

```APIDOC
## markAsRead

### Description
Marks all messages as "read" while fetching.

### Method
markAsRead

### Arguments
None

### Return
WhereQuery
```

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

### Fetch messages without body fetching

Source: https://github.com/webklex/php-imap/wiki/Advanced-fetching

Use setFetchBody(false) to retrieve messages without their body content, reducing server load. The query can filter by text or fetch all messages.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')->setFetchBody(false)->get();

/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()->setFetchBody(false)->get();
```

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

### Paginate a message collection

Source: https://github.com/webklex/php-imap/wiki/Pagination

Paginates a MessageCollection instance. Returns a LengthAwarePaginator.

```php
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $aMessage->paginate();
```

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

### Limit query results with limit(10, 2)

Source: https://github.com/webklex/php-imap/wiki/Result-limiting

Retrieves all messages for page 2 since March 15, 2018, with each page containing 10 messages. Uses the query builder's limit() method with page size and page number.

```php
/** @var \Webklex\PHPIMAP\Folder $oFolder */

//Get all messages for page 2 since march 15 2018 where each page contains 10 messages
/** @var \Webklex\PHPIMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->limit(10, 2)->get();
```

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

### Format PHP code in issues

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

Use markdown code blocks to format PHP code snippets when reporting issues to improve readability.

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

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

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

### setMask

Source: https://github.com/webklex/php-imap/wiki/Attachment::class

Set the mask class.

```APIDOC
## setMask

### Description
Set the mask class.

### Method
N/A

### Endpoint
N/A

### Parameters
- **mask** (string) - Required - The mask class name.

### Response
- **Return Type**: Attachment
- **Description**: The attachment instance for chaining.
```

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

### language

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given language.

```APIDOC
## language

### Description
Selects messages matching a given language.

### Method
language

### Arguments
- **$value** (string) - Required - The language to match.

### Return
WhereQuery
```

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

### orWhere

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Adds an OR condition to the query using a closure.

```APIDOC
## orWhere

### Description
If supported, performs an extended search request using an OR condition.

### Method
orWhere

### Arguments
- **$closure** (Closure) - Required - The closure defining the OR condition.

### Return
WhereQuery
```

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

### unseen

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects unseen messages.

```APIDOC
## unseen

### Description
Selects unseen messages.

### Method
unseen

### Arguments
None

### Return
WhereQuery
```

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

### count

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Counts all available messages matching the current search criteria.

```APIDOC
## count

### Description
Counts all available messages matching the current search criteria.

### Method
count

### Arguments
None

### Return
integer
```

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

### answered

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects answered messages.

```APIDOC
## answered

### Description
Selects answered messages.

### Method
answered

### Arguments
None

### Return
WhereQuery
```

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

### messageId

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given message id.

```APIDOC
## messageId

### Description
Selects messages matching a given message id.

### Method
messageId

### Arguments
- **$value** (string) - Required - The message id to match.

### Return
WhereQuery
```

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

### disconnect

Source: https://github.com/webklex/php-imap/wiki/Client::class

Disconnects from the server.

```APIDOC
## disconnect

### Description
Disconnect from server.

### Method
disconnect

### Parameters
None

### Return
None

```

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

### unanswered

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects unanswered messages.

```APIDOC
## unanswered

### Description
Selects unanswered messages.

### Method
unanswered

### Arguments
None

### Return
WhereQuery
```

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

### bcc

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given receiver (BCC:).

```APIDOC
## bcc

### Description
Selects messages matching a given receiver (BCC:).

### Method
bcc

### Arguments
- **$value** (string) - Required - The receiver address to match.

### Return
WhereQuery
```

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

### cc

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages matching a given receiver (CC:).

```APIDOC
## cc

### Description
Selects messages matching a given receiver (CC:).

### Method
cc

### Arguments
- **$value** (string) - Required - The receiver address to match.

### Return
WhereQuery
```

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

### not

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Negates the selection of messages.

```APIDOC
## not

### Description
Not select messages.

### Method
not

### Arguments
None

### Return
WhereQuery
```

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

### setTimeout

Source: https://github.com/webklex/php-imap/wiki/Client::class

Sets the timeout for certain IMAP operations.

```APIDOC
## setTimeout

### Description
Set the timeout for certain imap operations: 1: Open, 2: Read, 3: Write, 4: Close.

### Method
setTimeout

### Parameters
- **$type** (string or int) - Required - The operation type.
- **$timeout** (int) - Required - The timeout value.

### Return
- **boolean** - True on success, false on failure.

```

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

### noXSpam

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages that are not flagged as X-Spam.

```APIDOC
## noXSpam

### Description
Selects as no xspam flagged messages.

### Method
noXSpam

### Arguments
None

### Return
WhereQuery
```

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

### setDefaultMessageMask

Source: https://github.com/webklex/php-imap/wiki/Client::class

Sets the default message mask class.

```APIDOC
## setDefaultMessageMask

### Description
Set the default message mask class.

### Method
setDefaultMessageMask

### Parameters
- **$mask** (string) - Required - The mask class name.

### Return
- **self** - Returns the Client instance for chaining.

```

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

### getTimeout

Source: https://github.com/webklex/php-imap/wiki/Client::class

Retrieves the current timeout for a given operation type.

```APIDOC
## getTimeout

### Description
Check current mailbox.

### Method
getTimeout

### Parameters
- **$type** (string or int) - Required - The operation type.

### Return
- **int** - The timeout value.

```

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

### undeleted

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects undeleted messages.

```APIDOC
## undeleted

### Description
Selects undeleted messages.

### Method
undeleted

### Arguments
None

### Return
WhereQuery
```

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

### isXSpam

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects messages that are flagged as X-Spam.

```APIDOC
## isXSpam

### Description
Selects as xspam flagged messages.

### Method
isXSpam

### Arguments
None

### Return
WhereQuery
```

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

### deleted

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Selects deleted messages.

```APIDOC
## deleted

### Description
Selects deleted messages.

### Method
deleted

### Arguments
None

### Return
WhereQuery
```

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

### leaveUnread

Source: https://github.com/webklex/php-imap/wiki/WhereQuery::class

Prevents messages from being marked as read during fetching.

```APIDOC
## leaveUnread

### Description
Don't mark all messages as "read" while fetching.

### Method
leaveUnread

### Arguments
None

### Return
WhereQuery
```

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

### expunge

Source: https://github.com/webklex/php-imap/wiki/Client::class

Deletes all messages marked for deletion.

```APIDOC
## expunge

### Description
Delete all messages marked for deletion.

### Method
expunge

### Parameters
None

### Return
- **bool** - True on success, false on failure.

```
Tokens:
Raw