PHPackages                             justinkbruce/utilities - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. justinkbruce/utilities

ActiveProject[Utility & Helpers](/categories/utility)

justinkbruce/utilities
======================

utilities

0.025(1mo ago)0991PHPPHP ^8.2

Since Aug 22Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/justin-k-bruce/utilities)[ Packagist](https://packagist.org/packages/justinkbruce/utilities)[ RSS](/packages/justinkbruce-utilities/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (8)Dependencies (2)Versions (10)Used By (0)

Requirements
------------

[](#requirements)

- PHP 8.2+
- ext-imap

Installation
------------

[](#installation)

```
composer install
```

Unit Testing
------------

[](#unit-testing)

### How to create a unit test

[](#how-to-create-a-unit-test)

```
vendor/bin/codecept g:test unit
```

### Run tests

[](#run-tests)

```
vendor/bin/codecept run
```

How to use
----------

[](#how-to-use)

### Open IMAP connection

[](#open-imap-connection)

```
use Utilities\EmailReader;

$emailReader = new EmailReader("host", "username", "password", 993);

$mailBox = $emailReader->openMailBox("/imap/ssl");
```

Both port (default: `993`) and flags (default: `"/imap/ssl"`) are optional.

### Get an array of mailbox folders to choose from

[](#get-an-array-of-mailbox-folders-to-choose-from)

```
$folders = $emailReader->getMailBoxFolders();
```

### Open the desired mailbox folder from the returned array

[](#open-the-desired-mailbox-folder-from-the-returned-array)

Use the returned folders array to select which mailbox folder you want to open:

```
$mailBoxFolder = $emailReader->openMailBoxFolder($folders[0]);
```

### Get the headers of all the messages in the selected mailbox folder

[](#get-the-headers-of-all-the-messages-in-the-selected-mailbox-folder)

```
$headers = $emailReader->getMailBoxHeaders($mailBoxFolder);
```

### Read a selected message in the mailbox folder

[](#read-a-selected-message-in-the-mailbox-folder)

Select which message number you want to read from the mailbox folder:

```
$messageNumber = 418;

$email = $emailReader->getMessageData($messageNumber, $mailBoxFolder);
```

### Dump the attached files to a specified directory location

[](#dump-the-attached-files-to-a-specified-directory-location)

If there is an attachment on the email you want to download, supply the email data and a valid directory path:

```
$directory = "C:\\Users\\user\\Downloads\\";

$emailReader->dumpAttachments($email, $directory);
```

### Set message status

[](#set-message-status)

Set flags on messages using the `EmailFlag` enum:

```
use Utilities\EmailFlag;

$messageNumberSequence = 2;

$emailReader->setMessageStatus($messageNumberSequence, EmailFlag::Seen->value);
```

Available flags: `EmailFlag::Seen`, `EmailFlag::Flagged`, `EmailFlag::Deleted`, `EmailFlag::Draft`, `EmailFlag::Answered`.

### Clear message status

[](#clear-message-status)

Clear flags from messages using the `EmailFlag` enum:

```
use Utilities\EmailFlag;

$messageNumberSequence = 2;

$emailReader->clearMessageStatus($messageNumberSequence, EmailFlag::Seen->value);
```

### Move or copy messages to a different mailbox folder

[](#move-or-copy-messages-to-a-different-mailbox-folder)

**Important:** Some email servers require specific flags to be set before moving messages to a specific folder. For example, on a Gmail server, in order for messages to be moved to the Drafts folder (`[Gmail]/Drafts`) the message first needs to be flagged as `EmailFlag::Draft`.

#### Move:

[](#move)

```
$messageNumberSequence = 2;

$emailReader->messageMove($messageNumberSequence, $folders[2]);
```

#### Copy:

[](#copy)

```
$messageNumberSequence = 2;

$emailReader->messageCopy($messageNumberSequence, $folders[2]);
```

### Delete a message in the mailbox folder

[](#delete-a-message-in-the-mailbox-folder)

```
$messageNumber = 2;

$emailReader->messageDelete($messageNumber);
```

### Search for messages

[](#search-for-messages)

#### Search for message numbers containing specific criteria

[](#search-for-message-numbers-containing-specific-criteria)

Returns an array of message numbers containing the search criteria. A list of search criteria can be found here:

```
$searchCriteria = "SUBJECT \"test\"";

$searchResults = $emailReader->search($searchCriteria);
```

#### Get the headers for the search results

[](#get-the-headers-for-the-search-results)

Requires the search results from the initial search and returns the headers of all the searched emails:

```
$searchResultHeaders = $emailReader->getSearchResultHeaders($searchResults);
```

#### Extract message numbers from search result headers

[](#extract-message-numbers-from-search-result-headers)

```
$messageNumbers = $emailReader->getMessageNumbersForSearch($searchResultHeaders);
```

### Error handling

[](#error-handling)

All methods return an `EmailReaderError` instance on failure. Error codes are defined in the `ErrorCode` enum:

```
use Utilities\EmailReaderError;
use Utilities\ErrorCode;

$result = $emailReader->openMailBox();

if ($result instanceof EmailReaderError) {
    $error = $result->getError();
    echo $error->errorCode;    // e.g. "80002"
    echo $error->errorMessage; // e.g. "Failed to open imap stream"
}
```

### Close the IMAP connection

[](#close-the-imap-connection)

```
$emailReader->close();
```

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance93

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 79% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~346 days

Recently: every ~605 days

Total

8

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ebdaae67a3c7fd654bdcdcd13f7388cd4c98c632493f225343b4aaa8247de4cf?d=identicon)[JustinKBruce](/maintainers/JustinKBruce)

---

Top Contributors

[![justin-k-bruce](https://avatars.githubusercontent.com/u/22364123?v=4)](https://github.com/justin-k-bruce "justin-k-bruce (83 commits)")[![andrevanzuydam](https://avatars.githubusercontent.com/u/6102941?v=4)](https://github.com/andrevanzuydam "andrevanzuydam (20 commits)")[![jgbrits](https://avatars.githubusercontent.com/u/32747469?v=4)](https://github.com/jgbrits "jgbrits (2 commits)")

###  Code Quality

TestsCodeception

### Embed Badge

![Health badge](/badges/justinkbruce-utilities/health.svg)

```
[![Health](https://phpackages.com/badges/justinkbruce-utilities/health.svg)](https://phpackages.com/packages/justinkbruce-utilities)
```

###  Alternatives

[ultrono/laravelshoppingcart-1

Laravel 11 and above Shopping cart

1110.0k](/packages/ultrono-laravelshoppingcart-1)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)