aranxo / imap
A lightweight object-oriented wrapper around the PHP IMAP extension for reading mailboxes, messages and attachments.
Requires
- php: >=8.1
- ext-imap: *
- ext-json: *
- ext-mbstring: *
Requires (Dev)
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^10.5 || ^11.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 19:16:00 UTC
README
A wrapper class for IMAP mailbox access. Aranxo\Imap\Imap reads its
connection settings from a small JSON file and offers an object-oriented API
on top of the PHP IMAP extension: open folders, list and manage mailboxes,
read headers, bodies and attachments, and copy, move or delete messages.
The package consists of a single class and has no external Composer
dependencies.
Installation
composer require aranxo/imap
Requirements
- PHP ≥ 8.1
- PHP extensions
imap,mbstring,json - No external Composer dependencies
The IMAP extension
Since PHP 8.4.0 the IMAP extension is no longer bundled with PHP. It has been moved to the PECL repository (source: PHP manual, IMAP – Installation, and the PHP 8.4 migration guide, "Removed Extensions").
| PHP version | How to get the extension |
|---|---|
| PHP < 8.4 | The extension ships with PHP (compiled with --with-imap). It is usually already available or can be installed with your package manager, e.g. apt install php8.3-imap (Debian/Ubuntu); on Windows enable the bundled php_imap.dll. |
| PHP ≥ 8.4 | Install it from PECL with pecl install imap (package page: https://pecl.php.net/package/imap), or use your distribution's package (e.g. apt install php8.4-imap, dnf install php-imap). |
In both cases the extension has to be enabled in your php.ini:
extension=imap
Verify with php -m | grep imap or php -r 'var_dump(extension_loaded("imap"));'.
Configuration file
The constructor expects the path to a JSON file with an imap section.
A template is shipped as data/example.json:
{
"imap": {
"host": "imap.yourserver.com",
"port": 993,
"encryption": "SSL",
"selfsigned": false,
"username": "info@domain.de",
"password": "xyz0123456789"
}
}
encryption is appended to the mailbox string in lower case (e.g. /ssl,
/tls); set it to an empty string for an unencrypted connection. With
selfsigned: true the certificate is not validated (/novalidate-cert).
Class Aranxo\Imap\Imap
A wrapper class for IMAP mailbox access
Constructor, setters and getters
| Method | Description |
|---|---|
__construct(string $jsonfile) |
The Constructor. Sets credentials |
__destruct() |
The Destructor. Closes the connection and saves errors |
setCredentials(string $jsonfile): self |
Sets the credentials by reading a config json file |
setMessageFlags(int $flags = 0): self |
Sets the bitwise flags for message specific operations like FT_UID | FT_PEEK | FT_INTERNAL |
clearErrors(): self |
Clears the list of errors |
getMailbox(): string |
Gets the entire current mailbox string |
getHost(): string |
Gets the mail host |
getUsername(): string |
Gets the username |
getPassword(): string |
Gets the password |
getFolder(): string |
Gets the current mailbox folder |
getPort(): int |
Gets the used port |
getEncryption(): string |
Gets the used encryption |
getErrors(): array |
Gets the list of occured errors |
Connection
| Method | Description |
|---|---|
openFolder(string $folder = 'INBOX'): self |
Opens a folder. Encoding from utf-8 to utf-7 is included |
isConnected(): bool |
Checks if the stream is connected |
tickle(): void |
Assures that the current mailbox is (re)opened |
close(): void |
Closes the connection and deletes messages which are marked for deletion |
Mailboxes
| Method | Description |
|---|---|
getQuota(string $folder = 'INBOX'): array |
Gets the quota of a given mailbox |
getList(string $folder = ''): array |
Gets the list of all sub-mailboxes of a mailbox |
existsMailbox(string $folder = ''): bool |
Tests if a mailbox exists in the current connection |
getMailboxInfo(): array |
Gets general mailbox information of the current mailbox |
createMailbox(string $folder): bool |
Creates a mailbox in the current connection |
renameMailbox(string $from, string $to): bool |
Renames a mailbox in the current connection |
deleteMailbox(string $folder): bool |
Deletes a mailbox and all his sub-mailboxes in the current connection |
Messages
| Method | Description |
|---|---|
getMessageInfos(): array |
Gets detailed header informations for all messages in the active folder |
getHeader(int $messageId): array |
Gets detailed header information for the given message number |
fetchStructure(int $messageId) |
Gets structured information for a given message number |
analyseStructure(int $messageId, \stdClass $structure, string $partId = ''): array |
Analyses the structure given by imap_fetchstructure (Imap::fetchStructure()) and returns all relevant parts as array of arrays |
getBody(int $messageId, bool $html = false): string |
Gets the plain body or HTML body for the given message number |
getAttachments(int $messageId, int $flags = 3): array |
Gets the normal attachments or the inline attachments for the given message number |
getMessage(int $messageId): array |
Gets the entire email for the given message number |
saveAttachment(array $attachment, string $folder): bool |
Saves an attachment defined by an array with attachment parameters and a target folder |
copyMessage(int $messageId, string $folder): bool |
Copies an email into the given mailbox |
moveMessage(int $messageId, string $folder): bool |
Moves an email into the given mailbox |
deleteMessage(int $messageId, bool $immediate = false): bool |
Deletes the email with given message number |
Errors from the IMAP library are collected internally and can be inspected
with getErrors(); the destructor writes them to the PHP error log.
Usage
<?php require 'vendor/autoload.php'; use Aranxo\Imap\Imap; $imap = new Imap(__DIR__.'/data/example.json'); $imap->openFolder('INBOX'); foreach ($imap->getMessageInfos() as $info) { echo $info['msgno'], ': ', $info['subject'], PHP_EOL; } $imap->close();
Testing & static analysis
composer install composer test # PHPUnit composer analyse # PHPStan, level 8
The tests use the first existing file of data/hofmann.json, data/local.json
or data/example.json. With example.json only the offline tests run; put a
data/local.json with real credentials there (ignored by git) to also run the
live connection test.
License
MIT – see LICENSE.