 |
VOOZH | about |
|
VOOZH | about |
This document covers the attachment system for email messages in the hypervel/mail package. The Attachment class provides a fluent interface for attaching files to emails from various sources: filesystem paths, storage disks, or in-memory data. This page focuses on creating, configuring, and resolving attachments. For information about using attachments within Mailable classes, see Creating Mailable Classes. For the envelope and metadata configuration of emails, see Envelope and Metadata.
The attachment system uses a strategy pattern with deferred resolution. Instead of immediately loading file contents, the Attachment class stores a resolver closure that executes when the attachment is added to a mail message. This approach allows flexible handling of different attachment sources while maintaining consistent configuration.
Sources: src/Attachment.php1-162
The Attachment class provides three primary static factory methods for creating attachments from different sources. Each method returns a fluent Attachment instance that can be further configured.
The fromPath() method creates an attachment from a file located at a specific filesystem path. The attachment resolver uses a path strategy to attach the file when resolved.
Method Signature:
Attachment::fromPath(string $path): Attachment
Implementation: The resolver closure accepts a path strategy callback that handles attaching the file from the given path src/Attachment.php44-47
| Parameter | Type | Description |
|---|---|---|
$path | string | Absolute or relative filesystem path to the file |
Example Usage Context:
The fromStorage() and fromStorageDisk() methods create attachments from files stored in the application's storage system, leveraging the hypervel/filesystem integration.
Method Signatures:
Attachment::fromStorage(string $path): Attachment
Attachment::fromStorageDisk(?string $disk, string $path): Attachment
Implementation:
fromStorage() delegates to fromStorageDisk() with null disk (uses default) src/Attachment.php62-65fromStorageDisk() creates a resolver that retrieves the file from the specified storage disk src/Attachment.php70-79as() src/Attachment.php74FilesystemFactory to resolve the storage disk src/Attachment.php81-86| Parameter | Type | Description |
|---|---|---|
$disk | ?string | Storage disk name (null for default) |
$path | string | Path within the storage disk |
Example Usage Context:
The fromData() method creates an attachment from data generated at runtime or retrieved from memory, using a closure that returns the file contents.
Method Signature:
Attachment::fromData(Closure $data, ?string $name = null): Attachment
Implementation:
The resolver closure uses a data strategy that accepts a callback returning the attachment contents src/Attachment.php52-57 The optional $name parameter is passed to the as() method to set the filename.
| Parameter | Type | Description |
|---|---|---|
$data | Closure | Callback returning the file contents as a string |
$name | ?string | Optional filename for the attachment |
Example Usage Context:
Sources: src/Attachment.php44-79
Once created, attachments can be configured with metadata that controls how they appear in the email. All configuration methods return the Attachment instance for method chaining.
The as() method sets the filename that will appear in the email client when the recipient views or downloads the attachment.
Method Signature:
as(?string $name): Attachment
Implementation:
Stores the filename in the $as property src/Attachment.php91-96
The withMime() method explicitly sets the MIME type of the attachment, overriding automatic detection.
Method Signature:
withMime(string $mime): Attachment
Implementation:
Stores the MIME type in the $mime property src/Attachment.php103-108
The Attachment class stores configuration in public properties that can be accessed during resolution:
| Property | Type | Description |
|---|---|---|
$as | ?string | The attachment's display filename |
$mime | ?string | The attachment's MIME type |
These properties are defined at src/Attachment.php24 and src/Attachment.php29
Sources: src/Attachment.php24-108
The attachment system uses a strategy pattern to defer the actual file attachment until the mail message is being prepared. This design allows the same Attachment object to work with different mail implementations.
The attachWith() method executes the stored resolver closure with provided strategy callbacks. This is the core resolution mechanism.
Method Signature:
attachWith(Closure $pathStrategy, Closure $dataStrategy): mixed
Implementation: Invokes the resolver closure, passing itself and both strategies src/Attachment.php113-116
| Parameter | Type | Description |
|---|---|---|
$pathStrategy | Closure | Callback to handle file path attachments: fn(string $path, Attachment $attachment) |
$dataStrategy | Closure | Callback to handle data attachments: fn(Closure $data, Attachment $attachment) |
Resolution Flow:
fromPath()) creates resolver closureattachWith() is called with concrete strategiesThe attachTo() method provides a convenience wrapper for attaching to built-in mail types (Mailable, Message, or MailMessage).
Method Signature:
attachTo(Mailable|MailMessage|Message $mail, array $options = []): mixed
Implementation:
Calls attachWith() with strategies that invoke the mail object's attach() or attachData() methods src/Attachment.php123-144
Strategies:
$mail->attach($path, ['as' => ..., 'mime' => ...]) src/Attachment.php127-130$mail->attachData($data(), $name, ['mime' => ...]) src/Attachment.php131-142
RuntimeException if filename is not specified src/Attachment.php138-139| Parameter | Type | Description |
|---|---|---|
$mail | Mailable|MailMessage|Message | Target mail object |
$options | array | Optional overrides for as and mime |
Sources: src/Attachment.php113-144
Attachments integrate with Mailable classes through the attachments() method. The Mailable class processes the returned array of attachments during message preparation.
Mailable classes should define an attachments() method that returns an array of Attachment instances:
While Attachment provides the fluent interface, Mailable classes also expose lower-level attach() and attachData() methods that can be used directly (though the Attachment class is preferred for consistency):
attach(string $path, array $options) - Attach file from pathattachData(string|callable $data, string $name, array $options) - Attach raw dataThese methods are referenced in the attachment strategies src/Attachment.php127-142
Sources: src/Attachment.php123-144
The Attachment class provides an isEquivalent() method for comparing two attachment instances. This is useful for testing or deduplication.
Method Signature:
isEquivalent(Attachment $attachment, array $options = []): bool
Implementation: Resolves both attachments using identical strategies and compares the results src/Attachment.php149-161
Comparison Logic:
[data/path, options] tuples src/Attachment.php154-160===)| Parameter | Type | Description |
|---|---|---|
$attachment | Attachment | The attachment to compare against |
$options | array | Optional overrides for comparison (e.g., ['as' => 'name.pdf']) |
Sources: src/Attachment.php149-161
The Attachment class uses the Macroable trait src/Attachment.php19 allowing developers to dynamically add custom methods at runtime:
Sources: src/Attachment.php19
The attachment system provides a flexible, strategy-based approach to file attachments with three key characteristics:
attachments() methodKey Classes:
Attachment src/Attachment.php17-162 - Main attachment abstractionFilesystemFactory src/Attachment.php83-86 - Storage disk resolutionRelated Documentation:
Refresh this wiki