Skip to content

Commit 510543e

Browse files
mahatmamahardhikachmahatmamahardhikach
committed
docs: enhance Laravel documentation with detailed slot examples
- Added comprehensive slot usage examples - Structured content with table of contents - Explained basic, named slots, and conditional rendering
1 parent db40118 commit 510543e

File tree

10 files changed

+1400
-1021
lines changed

10 files changed

+1400
-1021
lines changed

‎pages/faq/framework/Laravel/envelop_mail_in_laravel.md

Lines changed: 144 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -9,158 +9,198 @@ description: "Envelop Mail In Laravel"
99

1010
# Enveloping Mail in Laravel
1111

12-
Laravel's `Envelope` feature, introduced in Laravel 9, allows developers to set up metadata for emails in a dedicated method, making it easier to organize various parts of an email. With the envelope approach, you can define properties like the subject, recipients, CC, BCC, and other headers in a structured way, rather than scattering them throughout the Mailable class.
12+
## Table of Contents
1313

14-
## What is the Envelope in Laravel?
14+
* [Introduction to Mail Enveloping](#introduction-to-mail-enveloping)
15+
* [Understanding Mail Envelopes](#understanding-mail-envelopes)
16+
* [Creating Mail Envelopes](#creating-mail-envelopes)
17+
* [Envelope Components](#envelope-components)
18+
* [Configuring Sender Information](#configuring-sender-information)
19+
* [Adding Recipients](#adding-recipients)
20+
* [Handling CC and BCC](#handling-cc-and-bcc)
21+
* [Subject Line Management](#subject-line-management)
22+
* [Attachments in Envelopes](#attachments-in-envelopes)
23+
* [Priority and Headers](#priority-and-headers)
24+
* [Advanced Envelope Techniques](#advanced-envelope-techniques)
25+
* [Error Handling](#error-handling)
26+
* [Best Practices](#best-practices)
27+
* [Conclusion](#conclusion)
1528

16-
The envelope acts as a "wrapper" for your email message, containing metadata for the email. You define it by adding the `envelope` method to your Mailable class. Laravel provides a dedicated `Envelope` class that you can use to specify the subject, sender, recipients, and other metadata.
29+
## Introduction to Mail Enveloping
1730

18-
## Creating a Mailable Class with an Envelope
31+
Mail enveloping in Laravel provides a robust and flexible way to manage email communication within your application. It
32+
offers a structured approach to creating, configuring, and sending emails with precise control over every aspect of the
33+
message.
1934

20-
Let’s go through the process of creating a Mailable class with the envelope functionality.
35+
## Understanding Mail Envelopes
2136

22-
### Step 1: Create a Mailable Class
37+
In Laravel, a mail envelope represents the metadata and configuration of an email before it is sent. It encapsulates
38+
critical information such as:
2339

24-
First, create a new Mailable class using Laravel’s Artisan command:
40+
- Sender details
41+
- Recipients
42+
- Subject line
43+
- Additional headers
44+
- Attachments
2545

26-
```bash
27-
php artisan make:mail OrderShipped
28-
```
29-
30-
This command will create a new Mailable class located in `app/Mail/OrderShipped.php`.
31-
32-
### Step 2: Define the Envelope Metadata
46+
## Creating Mail Envelopes
3347

34-
Open the `OrderShipped.php` file and add the `envelope` method. The `envelope` method returns an instance of Laravel's `Envelope` class, which allows you to set up the email’s metadata.
35-
36-
Here’s an example:
48+
Laravel 9 introduced the `Envelope` class to streamline mail configuration:
3749

3850
```php
39-
namespace App\Mail;
40-
41-
use Illuminate\Bus\Queueable;
42-
use Illuminate\Mail\Mailable;
43-
use Illuminate\Queue\SerializesModels;
4451
use Illuminate\Mail\Mailables\Envelope;
4552
use Illuminate\Mail\Mailables\Address;
4653

47-
class OrderShipped extends Mailable
54+
public function envelope(): Envelope
4855
{
49-
use Queueable, SerializesModels;
56+
return new Envelope(
57+
from: new Address('[email protected]', 'Sender Name'),
58+
to: [new Address('[email protected]', 'Recipient Name')],
59+
subject: 'Your Email Subject'
60+
);
61+
}
62+
```
5063

51-
public $order;
64+
## Envelope Components
5265

53-
public function __construct($order)
54-
{
55-
$this->order = $order;
56-
}
66+
An envelope consists of several key components:
5767

58-
public function envelope()
68+
```php
69+
class WelcomeMail extends Mailable
70+
{
71+
public function envelope(): Envelope
5972
{
6073
return new Envelope(
61-
subject: 'Your Order Has Shipped!',
62-
from: new Address('[email protected]', 'Your App'),
63-
to: [
64-
new Address($this->order->user->email, $this->order->user->name)
65-
],
66-
cc: [new Address('[email protected]', 'Support Team')],
67-
bcc: [new Address('[email protected]', 'Admin')],
68-
replyTo: [new Address('[email protected]', 'Support Team')]
74+
from: new Address('[email protected]', 'My Application'),
75+
replyTo: [new Address('[email protected]')],
76+
to: [new Address($this->user->email)],
77+
cc: [new Address('[email protected]')],
78+
bcc: [new Address('[email protected]')],
79+
subject: 'Welcome to Our Platform'
6980
);
7081
}
71-
72-
public function build()
73-
{
74-
return $this->view('emails.orders.shipped')
75-
->with([
76-
'order' => $this->order,
77-
]);
78-
}
7982
}
8083
```
8184

82-
### Explanation of the `Envelope` Method
83-
84-
In the `envelope` method:
85-
86-
- **subject**: Defines the subject line of the email.
87-
- **from**: Specifies the sender’s email address and name.
88-
- **to**: Sets the primary recipient(s) of the email.
89-
- **cc**: Defines additional recipients to receive a carbon copy of the email.
90-
- **bcc**: Sets recipients who will receive a blind carbon copy.
91-
- **replyTo**: Specifies the reply-to address, which allows the recipient to respond to a different address than the sender’s.
92-
93-
### Step 3: Setting Up the Email Template
94-
95-
Create an email template in `resources/views/emails/orders/shipped.blade.php` to define the content of your email. Here’s a basic template:
96-
97-
```html
98-
<!DOCTYPE html>
99-
<html>
100-
<head>
101-
<title>Your Order Has Shipped!</title>
102-
</head>
103-
<body>
104-
<h1>Order Shipped</h1>
105-
<p>Hello {{ '{{' }} $order->user->name }},</p>
106-
<p>Your order #{{ '{{' }} $order->id }} has been shipped and is on its way to you!</p>
107-
<p>Thank you for shopping with us.</p>
108-
</body>
109-
</html>
85+
## Configuring Sender Information
86+
87+
Multiple ways to configure sender details:
88+
89+
```php
90+
// Using configuration
91+
Mail::to($user)->send(new WelcomeMail());
92+
93+
// Manually specifying sender
94+
Mail::from('[email protected]')
95+
->to($user)
96+
->send(new WelcomeMail());
11097
```
11198

112-
### Step 4: Sending the Email with Envelop Metadata
99+
## Adding Recipients
113100

114-
To send the email, use the `Mail` facade and pass the `OrderShipped` mailable. The metadata specified in the `envelope` method will be automatically applied:
101+
Flexible recipient management:
115102

116103
```php
117-
use App\Mail\OrderShipped;
118-
use Illuminate\Support\Facades\Mail;
119-
120-
$order = Order::find(1);
121-
Mail::send(new OrderShipped($order));
104+
// Single recipient
105+
$envelope->to(new Address('[email protected]'));
106+
107+
// Multiple recipients
108+
$envelope->to([
109+
new Address('[email protected]'),
110+
new Address('[email protected]')
111+
]);
122112
```
123113

124-
## Benefits of Using the Envelope Feature
114+
## Handling CC and BCC
125115

126-
1. **Organization**: All metadata settings are placed in one method, making your Mailable class more organized.
127-
2. **Readability**: It’s easy to see the subject, sender, recipients, and other metadata at a glance.
128-
3. **Maintainability**: Updates to the email metadata are centralized in the `envelope` method, simplifying future changes.
129-
4. **Flexibility**: The `Envelope` class provides flexibility to customize various email headers based on your application’s needs.
116+
Manage carbon copy and blind carbon copy recipients:
130117

131-
## Additional Envelope Options
118+
```php
119+
return new Envelope(
120+
cc: [new Address('[email protected]')],
121+
bcc: [new Address('[email protected]')]
122+
);
123+
```
124+
125+
## Subject Line Management
132126

133-
The `Envelope` class supports additional options, like setting custom headers. Custom headers can be useful for tracking, categorizing, or filtering emails:
127+
Dynamic and conditional subject lines:
134128

135129
```php
136-
public function envelope()
130+
public function envelope(): Envelope
137131
{
138132
return new Envelope(
139-
subject: 'Your Order Has Shipped!',
140-
headers: [
141-
'X-Priority' => '1 (Highest)',
142-
'X-Mailer' => 'Laravel Mail'
143-
]
133+
subject: $this->order->isPriority()
134+
? 'Urgent Order Confirmation'
135+
: 'Order Confirmation'
144136
);
145137
}
146138
```
147139

148-
### Conditional Envelopes
140+
## Attachments in Envelopes
149141

150-
You can also conditionally set envelope properties based on specific conditions within your application:
142+
Adding attachments to your mail:
151143

152144
```php
153-
public function envelope()
145+
use Illuminate\Mail\Mailables\Attachment;
146+
147+
public function attachments(): array
154148
{
155-
$subject = $this->order->isUrgent ? 'Urgent Order Shipment!' : 'Your Order Has Shipped!';
156-
157-
return new Envelope(
158-
subject: $subject,
159-
to: [new Address($this->order->user->email, $this->order->user->name)]
160-
);
149+
return [
150+
Attachment::fromPath('/path/to/file.pdf')
151+
->as('report.pdf')
152+
->withMime('application/pdf')
153+
];
161154
}
162155
```
163156

157+
## Priority and Headers
158+
159+
Set email priority and custom headers:
160+
161+
```php
162+
return new Envelope(
163+
subject: 'Urgent Notification',
164+
headers: [
165+
'X-Priority' => 1,
166+
'X-Mailer' => 'Laravel Mailer'
167+
]
168+
);
169+
```
170+
171+
## Advanced Envelope Techniques
172+
173+
- Localized subject lines
174+
- Conditional recipient selection
175+
- Dynamic sender based on context
176+
177+
## Error Handling
178+
179+
Implement robust error management:
180+
181+
```php
182+
try {
183+
Mail::send(new WelcomeMail());
184+
} catch (Exception $e) {
185+
Log::error('Mail sending failed: ' . $e->getMessage());
186+
}
187+
```
188+
189+
## Best Practices
190+
191+
- Use meaningful, descriptive subjects
192+
- Validate recipient email addresses
193+
- Implement logging for email operations
194+
- Use environment-based configurations
195+
- Leverage Laravel's mail testing capabilities
196+
164197
## Conclusion
165198

166-
The Envelope feature in Laravel provides a more structured and powerful way to manage email metadata in your Mailable classes. By centralizing email metadata into a single method, you can maintain cleaner, more readable code, making your Mailable classes easier to manage. Whether you're sending simple notifications or complex transactional emails, the Envelope functionality offers a flexible solution for enhancing your email workflows in Laravel.
199+
Mail enveloping in Laravel represents a powerful abstraction for email communication. By providing a comprehensive,
200+
object-oriented approach to constructing emails, Laravel enables developers to create sophisticated, flexible, and
201+
maintainable email systems with minimal complexity.
202+
203+
The `Envelope` class and associated features demonstrate Laravel's commitment to providing elegant, developer-friendly
204+
solutions for common web application challenges. As email communication remains crucial in modern web applications,
205+
understanding and effectively utilizing mail enveloping can significantly enhance your application's communication
206+
capabilities.

0 commit comments

Comments
 (0)