1
- <p align =" center " >
2
- <img src =" /logo.png " >
3
- </p >
4
1
<p align =" center " >
5
2
<img src =" https://github.com/stackkit/laravel-database-emails/workflows/Run%20tests/badge.svg?branch=master " alt =" Build Status " >
6
3
<a href =" https://packagist.org/packages/stackkit/laravel-database-emails " ><img src =" https://poser.pugx.org/stackkit/laravel-database-emails/v/stable.svg " alt =" Latest Stable Version " ></a >
7
4
<a href =" https://packagist.org/packages/stackkit/laravel-database-emails " ><img src =" https://poser.pugx.org/stackkit/laravel-database-emails/license.svg " alt =" License " ></a >
8
5
</p >
9
6
10
- # Package Documentation
11
-
12
- This package allows you to store and send e-mails using a database.
7
+ # Introduction
13
8
14
- ## Contribution
15
-
16
- The package is MIT licenced, meaning it's open source and you are free to copy or fork it and modify it any way you wish.
17
-
18
- We feel the package is currently feature complete, but feel free to send a pull request or help improve existing code.
9
+ This package allows you to store and send e-mails using the database.
19
10
20
11
# Requirements
21
12
22
- This package requires Laravel 6.0 or higher.
23
-
24
- Please check the [ Laravel support policy] ( https://laravel.com/docs/master/releases#support-policy ) table for supported Laravel and PHP versions.
13
+ This package requires Laravel 10 or 11.
25
14
26
15
# Installation
27
16
28
17
Require the package using composer.
29
18
30
- ``` bash
19
+ ``` shell
31
20
composer require stackkit/laravel-database-emails
32
21
```
33
22
34
23
Publish the configuration files.
35
24
36
- ``` bash
37
- php artisan vendor:publish --tag=laravel-database-emails-config
25
+ ``` shell
26
+ php artisan vendor:publish --tag=database-emails-config
27
+ php artisan vendor:publish --tag=database-emails-migrations
38
28
```
39
29
40
30
Create the database table required for this package.
41
31
42
- ``` bash
32
+ ``` shell
43
33
php artisan migrate
44
34
```
45
35
46
36
Add the e-mail cronjob to your scheduler
47
37
48
38
``` php
49
- <?php
50
-
51
- /**
52
- * Define the application's command schedule.
53
- *
54
- * @param \Illuminate\Console\Scheduling\Schedule $schedule
55
- * @return void
56
- */
57
39
protected function schedule(Schedule $schedule)
58
40
{
59
41
$schedule->command('email:send')->everyMinute()->withoutOverlapping(5);
@@ -65,192 +47,187 @@ protected function schedule(Schedule $schedule)
65
47
66
48
### Send an email
67
49
68
- ``` php
69
- <?php
50
+ E-mails are composed the same way mailables are created.
70
51
52
+ ``` php
71
53
use Stackkit\LaravelDatabaseEmails\Email;
54
+ use Illuminate\Mail\Mailables\Content;
55
+ use Stackkit\LaravelDatabaseEmails\Attachment;
56
+ use Illuminate\Mail\Mailables\Envelope;
72
57
73
58
Email::compose()
74
- ->label('welcome')
75
-
76
- ->subject('This is a test')
77
- ->view('emails.welcome')
78
- ->variables([
79
- 'name' => 'John Doe',
59
+ ->content(fn (Content $content) => $content
60
+ ->view('tests::dummy')
61
+ ->with(['name' => 'John Doe'])
62
+ )
63
+ ->envelope(fn (Envelope $envelope) => $envelope
64
+ ->subject('Hello')
65
+ ->from('
[email protected] ', 'John Doe')
66
+ ->to('
[email protected] ', 'Jane Doe')
67
+ )
68
+ ->attachments([
69
+ Attachment::fromStorageDisk('s3', '/invoices/john-doe/march-2024.pdf'),
80
70
])
81
71
->send();
72
+ ])
82
73
```
83
74
84
- ### Specify multiple recipients
75
+ ### Sending emails to users in your application
85
76
86
77
``` php
87
- <?php
88
-
89
- use Stackkit\LaravelDatabaseEmails\Email;
90
-
91
78
Email::compose()
92
- ->recipient([
93
-
94
-
95
- ]);
79
+ ->user($user)
80
+ ->send();
96
81
```
97
82
98
- ### CC and BCC
83
+ By default, the ` name ` column will be used to set the recipient's name. If you wish to use something different, you should implement the ` preferredEmailName ` method in your model.
99
84
100
85
``` php
101
- <?php
102
-
103
- use Stackkit\LaravelDatabaseEmails\Email;
104
-
105
- Email::compose()
106
-
107
-
108
-
109
-
86
+ class User extends Model
87
+ {
88
+ public function preferredEmailName(): string
89
+ {
90
+ return $this->first_name;
91
+ }
92
+ }
110
93
```
111
94
112
- ### Reply-To
95
+ By default, the ` email ` column will be used to set the recipient's e-mail address. If you wish to use something different, you should implement the ` preferredEmailAddress ` method in your model.
113
96
114
97
``` php
115
- <?php
116
-
117
- use Stackkit\LaravelDatabaseEmails\Email;
118
-
119
- Email::compose()
120
-
98
+ class User extends Model
99
+ {
100
+ public function preferredEmailAddress(): string
101
+ {
102
+ return $this->work_email;
103
+ }
104
+ }
105
+ ```
121
106
122
- Email::compose()
123
- ->replyTo(new Address('
[email protected] ', 'John Doe'));
107
+ By default, the app locale will be used. If you wish to use something different, you should implement the ` preferredEmailLocale ` method in your model.
124
108
125
- Email::compose()
126
- ->replyTo([
127
- new Address('
[email protected] ', 'John Doe'),
128
- new Address('
[email protected] ', 'Jane Doe'),
129
- ]);
109
+ ``` php
110
+ class User extends Model implements HasLocalePreference
111
+ {
112
+ public function preferredLocale(): string
113
+ {
114
+ return $this->locale;
115
+ }
116
+ }
130
117
```
131
118
132
119
### Using mailables
133
120
134
121
You may also pass a mailable to the e-mail composer.
135
122
136
123
``` php
137
- <?php
138
-
139
- use Stackkit\LaravelDatabaseEmails\Email;
140
-
141
124
Email::compose()
142
125
->mailable(new OrderShipped())
143
126
->send();
144
127
```
145
128
146
129
### Attachments
147
130
148
- ``` php
149
- <?php
150
-
151
- use Stackkit\LaravelDatabaseEmails\Email;
152
-
153
- Email::compose()
154
- ->attach('/path/to/file');
155
- ```
131
+ To start attaching files to your e-mails, you may use the ` attachments ` method like you normally would in Laravel.
132
+ However, you will have to use this package's ` Attachment ` class.
156
133
157
- Or for in-memory attachments:
158
134
159
135
``` php
160
- <?php
161
-
162
- use Stackkit\LaravelDatabaseEmails\Email;
163
-
164
136
Email::compose()
165
- ->attachData('<p >Your order has shipped!</p >', 'order.html');
137
+ ->attachments([
138
+ Attachment::fromPath(__DIR__.'/files/pdf-sample.pdf'),
139
+ Attachment::fromPath(__DIR__.'/files/my-file.txt')->as('Test123 file'),
140
+ Attachment::fromStorageDisk('my-custom-disk', 'test.txt'),
141
+ ])
142
+ ->send();
166
143
```
167
144
168
- ### Custom Sender
145
+ > [ !NOTE]
146
+ > ` Attachment::fromData() ` and ` Attachment::fromStorage() ` are not supported as they work with raw data.
169
147
170
- ``` php
171
- <?php
148
+ ### Attaching models to e-mails
172
149
173
- use Stackkit\LaravelDatabaseEmails\Email;
150
+ You may attach a model to an e-mail. This can be useful to attach a user or another model that belongs to the e-mail.
174
151
152
+ ``` php
175
153
Email::compose()
176
- ->
from('[email protected] ', 'John Doe' );
154
+ ->model(User::find(1) );
177
155
```
178
156
179
157
### Scheduling
180
158
181
159
You may schedule an e-mail by calling ` later ` instead of ` send ` . You must provide a Carbon instance or a strtotime valid date.
182
160
183
161
``` php
184
- <?php
185
-
186
- use Stackkit\LaravelDatabaseEmails\Email;
187
-
188
162
Email::compose()
189
163
->later('+2 hours');
190
164
```
191
165
192
- ### Encryption (Optional)
166
+ ### Queueing e-mails
167
+
168
+ > [ !IMPORTANT]
169
+ > When queueing mail using the ` queue ` function, it is no longer necessary to schedule the ` email:send ` command.
193
170
194
- If you wish to encrypt your e-mails, please enable the ` encrypt ` option in the configuration file. This is disabled by default. Encryption and decryption will be handled by Laravel's built-in encryption mechanism. Please note that by encrypting the e-mail it takes more disk space.
171
+ ``` php
172
+ Email::compose()->queue();
195
173
196
- ``` text
197
- Without encryption
174
+ // On a specific connection
175
+ Email::compose()->queue(connection: 'sqs');
198
176
199
- 7 bytes (label)
200
- 16 bytes (recipient)
201
- 20 bytes (subject)
202
- 48 bytes (view name)
203
- 116 bytes (variables)
204
- 1874 bytes (e-mail content)
205
- 4 bytes (attempts, sending, failed, encrypted)
206
- 57 bytes (created_at, updated_at, deleted_at)
207
- ... x 10.000 rows = ± 21.55 MB
177
+ // On a specific queue
178
+ Email::compose()->queue(queue: 'email-queue');
208
179
209
- With encryption the table size is ± 50.58 MB.
180
+ // Delay (send mail in 10 minutes)
181
+ Email::compose()->queue(delay: now()->addMinutes(10));
210
182
```
211
183
184
+ If you need more flexibility, you may also pass your own job class:
212
185
213
- ### Queueing e-mails
186
+ ``` php
187
+ Email::compose()->queue(jobClass: CustomSendEmailJob::class);
188
+ ```
214
189
215
- ** Important ** : When queueing mail using the ` queue ` function, it is no longer necessary to schedule the ` email:send ` command. Please make sure it is removed from ` app/Console/Kernel.php ` .
190
+ It could look like this:
216
191
217
192
``` php
218
193
<?php
219
194
220
- use Stackkit\LaravelDatabaseEmails\Email;
221
-
222
- Email::compose()
223
- ->queue();
224
-
225
- // on a specific connection
226
- Email::compose()
227
- ->queue('sqs');
195
+ namespace App\Jobs;
228
196
229
- // on a specific queue
230
- Email::compose()
231
- ->queue(null, 'email-queue');
197
+ use Illuminate\Contracts\Queue\ShouldQueue;
198
+ use Stackkit\LaravelDatabaseEmails\SendEmailJob;
232
199
233
- // timeout (send mail in 10 minutes)
234
- Email::compose()
235
- ->queue(null, null, now()->addMinutes(10));
200
+ class CustomSendEmailJob extends SendEmailJob implements ShouldQueue
201
+ {
202
+ // Define custom retries, backoff, etc...
203
+ }
236
204
```
237
205
238
- ### Test mode (Optional)
206
+ ### Test mode
239
207
240
208
When enabled, all newly created e-mails will be sent to the specified test e-mail address. This is turned off by default.
241
209
210
+ ``` dotenv
211
+ DB_EMAILS_TESTING_ENABLED=true
212
+
213
+ ```
214
+
242
215
### E-mails to send per minute
243
216
244
- To configure how many e-mails should be sent each command, please check the ` limit ` option. The default is ` 20 ` e-mails every command .
217
+ To configure how many e-mails should be sent each command.
245
218
246
- ### Send e-mails immediately (Optional)
219
+ ``` dotenv
220
+ DB_EMAILS_LIMIT=20
221
+ ```
222
+
223
+ ### Send e-mails immediately
247
224
248
225
Useful during development when Laravel Scheduler is not running
249
226
250
227
To enable, set the following environment variable:
251
228
252
- ```
253
- LARAVEL_DATABASE_EMAILS_SEND_IMMEDIATELY =true
229
+ ``` dotenv
230
+ DB_EMAILS_IMMEDIATELY =true
254
231
```
255
232
256
233
### Pruning models
@@ -260,7 +237,7 @@ use Stackkit\LaravelDatabaseEmails\Email;
260
237
261
238
$schedule->command('model:prune', [
262
239
'--model' => [Email::class],
263
- ])->everyMinute ();
240
+ ])->daily ();
264
241
```
265
242
266
243
By default, e-mails are pruned when they are older than 6 months.
0 commit comments