Search by

aranxo / imap

Aranxo

A lightweight object-oriented wrapper around the PHP IMAP extension for reading mailboxes, messages and attachments.

Package info

github.com/Aranxo/imap

pkg:composer/aranxo/imap

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

dev-main 2026-11-19 19:01 UTC

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.