Skip to content

Commit 2816911

Browse files
Merge pull request #60 from stackkit/7.x
7.x
2 parents 0caa189 + 1c76345 commit 2816911

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+1285
-2740
lines changed

.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,5 @@ vendor/
44
composer.lock
55
.phpunit.result.cache
66
.phpunit.cache
7+
test
8+

README.md

+107-130
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,41 @@
1-
<p align="center">
2-
<img src="/logo.png">
3-
</p>
41
<p align="center">
52
<img src="https://github.com/stackkit/laravel-database-emails/workflows/Run%20tests/badge.svg?branch=master" alt="Build Status">
63
<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>
74
<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>
85
</p>
96

10-
# Package Documentation
11-
12-
This package allows you to store and send e-mails using a database.
7+
# Introduction
138

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.
1910

2011
# Requirements
2112

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.
2514

2615
# Installation
2716

2817
Require the package using composer.
2918

30-
```bash
19+
```shell
3120
composer require stackkit/laravel-database-emails
3221
```
3322

3423
Publish the configuration files.
3524

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
3828
```
3929

4030
Create the database table required for this package.
4131

42-
```bash
32+
```shell
4333
php artisan migrate
4434
```
4535

4636
Add the e-mail cronjob to your scheduler
4737

4838
```php
49-
<?php
50-
51-
/**
52-
* Define the application's command schedule.
53-
*
54-
* @param \Illuminate\Console\Scheduling\Schedule $schedule
55-
* @return void
56-
*/
5739
protected function schedule(Schedule $schedule)
5840
{
5941
$schedule->command('email:send')->everyMinute()->withoutOverlapping(5);
@@ -65,192 +47,187 @@ protected function schedule(Schedule $schedule)
6547

6648
### Send an email
6749

68-
```php
69-
<?php
50+
E-mails are composed the same way mailables are created.
7051

52+
```php
7153
use Stackkit\LaravelDatabaseEmails\Email;
54+
use Illuminate\Mail\Mailables\Content;
55+
use Stackkit\LaravelDatabaseEmails\Attachment;
56+
use Illuminate\Mail\Mailables\Envelope;
7257

7358
Email::compose()
74-
->label('welcome')
75-
->recipient('[email protected]')
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'),
8070
])
8171
->send();
72+
])
8273
```
8374

84-
### Specify multiple recipients
75+
### Sending emails to users in your application
8576

8677
```php
87-
<?php
88-
89-
use Stackkit\LaravelDatabaseEmails\Email;
90-
9178
Email::compose()
92-
->recipient([
93-
94-
95-
]);
79+
->user($user)
80+
->send();
9681
```
9782

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.
9984

10085
```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+
}
11093
```
11194

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.
11396

11497
```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+
```
121106

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.
124108

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+
}
130117
```
131118

132119
### Using mailables
133120

134121
You may also pass a mailable to the e-mail composer.
135122

136123
```php
137-
<?php
138-
139-
use Stackkit\LaravelDatabaseEmails\Email;
140-
141124
Email::compose()
142125
->mailable(new OrderShipped())
143126
->send();
144127
```
145128

146129
### Attachments
147130

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.
156133

157-
Or for in-memory attachments:
158134

159135
```php
160-
<?php
161-
162-
use Stackkit\LaravelDatabaseEmails\Email;
163-
164136
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();
166143
```
167144

168-
### Custom Sender
145+
> [!NOTE]
146+
> `Attachment::fromData()` and `Attachment::fromStorage()` are not supported as they work with raw data.
169147
170-
```php
171-
<?php
148+
### Attaching models to e-mails
172149

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.
174151

152+
```php
175153
Email::compose()
176-
->from('[email protected]', 'John Doe');
154+
->model(User::find(1));
177155
```
178156

179157
### Scheduling
180158

181159
You may schedule an e-mail by calling `later` instead of `send`. You must provide a Carbon instance or a strtotime valid date.
182160

183161
```php
184-
<?php
185-
186-
use Stackkit\LaravelDatabaseEmails\Email;
187-
188162
Email::compose()
189163
->later('+2 hours');
190164
```
191165

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.
193170
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();
195173

196-
```text
197-
Without encryption
174+
// On a specific connection
175+
Email::compose()->queue(connection: 'sqs');
198176

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');
208179

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));
210182
```
211183

184+
If you need more flexibility, you may also pass your own job class:
212185

213-
### Queueing e-mails
186+
```php
187+
Email::compose()->queue(jobClass: CustomSendEmailJob::class);
188+
```
214189

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:
216191

217192
```php
218193
<?php
219194

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;
228196

229-
// on a specific queue
230-
Email::compose()
231-
->queue(null, 'email-queue');
197+
use Illuminate\Contracts\Queue\ShouldQueue;
198+
use Stackkit\LaravelDatabaseEmails\SendEmailJob;
232199

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+
}
236204
```
237205

238-
### Test mode (Optional)
206+
### Test mode
239207

240208
When enabled, all newly created e-mails will be sent to the specified test e-mail address. This is turned off by default.
241209

210+
```dotenv
211+
DB_EMAILS_TESTING_ENABLED=true
212+
213+
```
214+
242215
### E-mails to send per minute
243216

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.
245218

246-
### Send e-mails immediately (Optional)
219+
```dotenv
220+
DB_EMAILS_LIMIT=20
221+
```
222+
223+
### Send e-mails immediately
247224

248225
Useful during development when Laravel Scheduler is not running
249226

250227
To enable, set the following environment variable:
251228

252-
```
253-
LARAVEL_DATABASE_EMAILS_SEND_IMMEDIATELY=true
229+
```dotenv
230+
DB_EMAILS_IMMEDIATELY=true
254231
```
255232

256233
### Pruning models
@@ -260,7 +237,7 @@ use Stackkit\LaravelDatabaseEmails\Email;
260237

261238
$schedule->command('model:prune', [
262239
'--model' => [Email::class],
263-
])->everyMinute();
240+
])->daily();
264241
```
265242

266243
By default, e-mails are pruned when they are older than 6 months.

0 commit comments

Comments
 (0)