Skip to content

Commit e69bd9c

Browse files
committed
Update readme.md
1 parent 023c33c commit e69bd9c

File tree

1 file changed

+21
-23
lines changed

1 file changed

+21
-23
lines changed

readme.md

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,7 @@ You can install the package via composer:
2525
composer require directorytree/imapengine
2626
```
2727

28-
## Usage
29-
30-
### Configuration
28+
## Configuration
3129

3230
All default configuration options are shown below:
3331

@@ -51,7 +49,7 @@ $config = [
5149
];
5250
```
5351

54-
### Connection
52+
## Connection
5553

5654
To connect to a mailbox, create a new `Mailbox` instance with the above configuration options:
5755

@@ -80,9 +78,9 @@ $mailbox = new Mailbox([
8078
]);
8179
```
8280

83-
### Usage
81+
## Usage
8482

85-
#### Retrieving Folders
83+
### Retrieving Folders
8684

8785
```php
8886
// Get the mailbox's inbox folder.
@@ -98,7 +96,7 @@ $folders = $mailbox->folders()->get('*/Subfolder');
9896
$folder = $mailbox->folders()->find('Folder Name');
9997
```
10098

101-
#### Retrieving Messages
99+
### Retrieving Messages
102100

103101
ImapEngine provides a fluent, chainable API for building advanced message search queries.
104102

@@ -112,7 +110,7 @@ $inbox = $mailbox->folders()->inbox();
112110
// Get all message UIDs in the inbox.
113111
$messages = $inbox->messages()->get();
114112

115-
// Get all messages in the inbox with various content.
113+
// Get all messages in the inbox with various content enabled.
116114
$messages = $inbox->messages()
117115
->withHeaders() // Enable fetching message headers.
118116
->withFlags() // Enable fetching message flags.
@@ -132,7 +130,7 @@ $messages = $inbox->messages()
132130
> A typical approach when dealing with large mailboxes is to store all messages (either in a cache or DB)
133131
> once, and then only fetch new messages since the last time the mailbox was checked.
134132
135-
##### Filtering By Criteria
133+
#### Filtering By Criteria
136134

137135
The MessageQuery supports many common IMAP search criteria. You can chain methods such as:
138136

@@ -184,9 +182,9 @@ $messages = $inbox->messages()
184182
->get();
185183
```
186184

187-
##### Fetching Additional Message Data
185+
#### Fetching Additional Message Data
188186

189-
You can control what parts of the message are fetched by enabling or disabling them on the query builder:
187+
By default, ImapEngine only fetches UIDs. To fetch additional message data, you have to enable it explicitly.
190188

191189
**Message Headers:**
192190
Use `withHeaders()` to include headers in the result, or `withoutHeaders()` to exclude them.
@@ -213,7 +211,7 @@ $messages = $inbox->messages()
213211

214212
The less data you fetch, the faster your query will be. Only fetch the data you need.
215213

216-
##### Message Pagination
214+
#### Message Pagination
217215

218216
You can paginate messages using the `paginate()` method. This method accepts the number of messages to display per page:
219217

@@ -227,7 +225,7 @@ You can paginate messages using the `paginate()` method. This method accepts the
227225
$paginatedMessages = $inbox->messages()->paginate(10);
228226
```
229227

230-
##### Message Chunking
228+
#### Message Chunking
231229

232230
If you need to process a large number of messages without loading them all at once, you can use the chunk() method:
233231

@@ -239,7 +237,7 @@ $inbox->messages()->chunk(function ($chunk, $page) {
239237
}, 20); // Process 20 messages per chunk.
240238
```
241239

242-
##### Finding a Specific Message
240+
#### Finding a Specific Message
243241

244242
You can retrieve a single message by its unique identifier using the `find()` method.
245243

@@ -259,13 +257,13 @@ Or by message sequence number:
259257
$message = $inbox->messages()->find(1, ImapFetchIdentifier::MessageNumber);
260258
```
261259

262-
#### Interacting With Messages
260+
### Interacting With Messages
263261

264262
Once you retrieve messages from a folder using methods like `$inbox->messages()->get()`, you'll receive instances of the `Message` class.
265263

266264
This class offers a rich set of helper methods for interacting with individual emails, making it easy to inspect, modify, and manipulate messages.
267265

268-
##### Retrieving Message Information
266+
#### Retrieving Message Information
269267

270268
The `Message` class provides several methods to access basic properties:
271269

@@ -283,7 +281,7 @@ The `Message` class provides several methods to access basic properties:
283281
- `date()`: Returns the message’s date as a Carbon instance (if available).
284282
- `messageId()`: Retrieves the Message-ID header (globally unique identifier for the message).
285283

286-
##### Address Handling
284+
#### Address Handling
287285

288286
To conveniently work with email addresses, the `Message` class includes methods that return addresses as instances of the `Address` class:
289287

@@ -295,22 +293,22 @@ To conveniently work with email addresses, the `Message` class includes methods
295293
- `cc()`: An array of CC addresses.
296294
- `bcc()`: An array of BCC addresses.
297295

298-
##### Content Retrieval
296+
#### Content Retrieval
299297

300298
For accessing the message content in different formats:
301299

302300
- `html()`: Returns the HTML version of the message (if available).
303301
- `text()`: Returns the plain text version of the message (if available).
304302

305-
##### Attachment Handling
303+
#### Attachment Handling
306304

307305
Messages that include attachments can be inspected with:
308306

309307
- `attachments()`: Returns an array of `Attachment` objects.
310308
- `hasAttachments()`: Checks if the message contains any attachments.
311309
- `attachmentCount()`: Returns the number of attachments in the message.
312310

313-
##### Flag Operations
311+
#### Flag Operations
314312

315313
The class also provides methods to modify message flags, which help you manage the state of a message:
316314

@@ -328,23 +326,23 @@ The class also provides methods to modify message flags, which help you manage t
328326

329327
All these methods work by invoking the underlying IMAP `STORE` command (with the appropriate flag and operation), and optionally expunging the folder afterward.
330328

331-
##### Message Manipulation
329+
#### Message Manipulation
332330

333331
Beyond just flagging, you can move or copy messages between folders, or even delete them:
334332

335333
- `copy(string $folder, bool $expunge = true)`: Copies the message to the specified folder.
336334
- `move(string $folder, bool $expunge = true)`: Moves the message to the specified folder.
337335
- `delete(bool $expunge = true)`: Marks the message as deleted and, if desired, expunges it from the folder.
338336

339-
##### Parsing and String Conversion
337+
#### Parsing and String Conversion
340338

341339
- `parse()`: Parses the raw message data into a `MailMimeMessage` instance for deeper inspection (e.g., extracting structured content, attachments, etc.).
342340
> **Note:** An exception is thrown if both headers and contents are empty.
343341
- `__toString()`: Converts the message back to its full raw string (headers and contents combined), which is useful for logging or re-sending the email.
344342

345343
---
346344

347-
##### Example: Interacting with a Retrieved Message
345+
#### Example: Interacting with a Retrieved Message
348346

349347
```php
350348
// Retrieve the first message from the inbox.

0 commit comments

Comments
 (0)