Merge pull request #60 from stackkit/7.x

7.x

Author: marickvantuil

.gitignore

@@ -4,3 +4,5 @@ vendor/
 composer.lock
 .phpunit.result.cache
 .phpunit.cache
+test
+

README.md

@@ -1,59 +1,41 @@
-<p align="center">
-  <img src="/logo.png">
-</p>
 <p align="center">
 <img src="https://github.com/stackkit/laravel-database-emails/workflows/Run%20tests/badge.svg?branch=master" alt="Build Status">
 <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>
 <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>
 </p>
 
-# Package Documentation
-
-This package allows you to store and send e-mails using a database. 
+# Introduction
 
-## Contribution
-
-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.
-
-We feel the package is currently feature complete, but feel free to send a pull request or help improve existing code.
+This package allows you to store and send e-mails using the database. 
 
 # Requirements
 
-This package requires Laravel 6.0 or higher.
-
-Please check the [Laravel support policy](https://laravel.com/docs/master/releases#support-policy) table for supported Laravel and PHP versions.
+This package requires Laravel 10 or 11.
 
 # Installation
 
 Require the package using composer.
 
-```bash
+```shell
 composer require stackkit/laravel-database-emails
 ```
 
 Publish the configuration files.
 
-```bash
-php artisan vendor:publish --tag=laravel-database-emails-config
+```shell
+php artisan vendor:publish --tag=database-emails-config
+php artisan vendor:publish --tag=database-emails-migrations
 ```
 
 Create the database table required for this package.
 
-```bash
+```shell
 php artisan migrate
 ```
 
 Add the e-mail cronjob to your scheduler
 
 ```php
-<?php
-
-/**
- * Define the application's command schedule.
- *
- * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
- * @return void
- */
 protected function schedule(Schedule $schedule)
 {
      $schedule->command('email:send')->everyMinute()->withoutOverlapping(5);
@@ -65,192 +47,187 @@ protected function schedule(Schedule $schedule)
 
 ### Send an email
 
-```php
-<?php
+E-mails are composed the same way mailables are created.
 
+```php
 use Stackkit\LaravelDatabaseEmails\Email;
+use Illuminate\Mail\Mailables\Content;
+use Stackkit\LaravelDatabaseEmails\Attachment;
+use Illuminate\Mail\Mailables\Envelope;
 
 Email::compose()
-    ->label('welcome')
-    ->recipient('john@doe.com')
-    ->subject('This is a test')
-    ->view('emails.welcome')
-    ->variables([
-        'name' => 'John Doe',
+    ->content(fn (Content $content) => $content
+        ->view('tests::dummy')
+        ->with(['name' => 'John Doe'])
+    )
+    ->envelope(fn (Envelope $envelope) => $envelope
+        ->subject('Hello')
+        ->from('johndoe@example.com', 'John Doe')
+        ->to('janedoe@example.com', 'Jane Doe')
+    )
+    ->attachments([
+        Attachment::fromStorageDisk('s3', '/invoices/john-doe/march-2024.pdf'),
     ])
     ->send();
+])
 ```
 
-### Specify multiple recipients
+### Sending emails to users in your application
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
 Email::compose()
-    ->recipient([
-        'john@doe.com',
-        'jane@doe.com'
-    ]);
+    ->user($user)
+    ->send();
 ```
 
-### CC and BCC
+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.
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
-Email::compose()
-    ->cc('john@doe.com')
-    ->cc(['john@doe.com', 'jane@doe.com'])
-    ->bcc('john@doe.com')
-    ->bcc(['john@doe.com', 'jane@doe.com']);
+class User extends Model
+{
+    public function preferredEmailName(): string
+    {
+        return $this->first_name;
+    }
+}
 ```
 
-### Reply-To
+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.
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
-Email::compose()
-    ->replyTo(['john@doe.com', 'jane@doe.com']);
+class User extends Model
+{
+    public function preferredEmailAddress(): string
+    {
+        return $this->work_email;
+    }
+}
+```
 
-Email::compose()
-    ->replyTo(new Address('john@doe.com', 'John Doe'));
+By default, the app locale will be used. If you wish to use something different, you should implement the `preferredEmailLocale` method in your model.
 
-Email::compose()
-    ->replyTo([
-        new Address('john@doe.com', 'John Doe'),
-        new Address('jane@doe.com', 'Jane Doe'),
-    ]);
+```php
+class User extends Model implements HasLocalePreference
+{
+    public function preferredLocale(): string
+    {
+        return $this->locale;
+    }
+}
 ```
 
 ### Using mailables
 
 You may also pass a mailable to the e-mail composer.
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
 Email::compose()
     ->mailable(new OrderShipped())
     ->send();
 ```
 
 ### Attachments
 
-```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
-Email::compose()
-    ->attach('/path/to/file');
-```
+To start attaching files to your e-mails, you may use the `attachments` method like you normally would in Laravel.
+However, you will have to use this package's `Attachment` class.
 
-Or for in-memory attachments:
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
 Email::compose()
-    ->attachData('<p>Your order has shipped!</p>', 'order.html');
+    ->attachments([
+        Attachment::fromPath(__DIR__.'/files/pdf-sample.pdf'),
+        Attachment::fromPath(__DIR__.'/files/my-file.txt')->as('Test123 file'),
+        Attachment::fromStorageDisk('my-custom-disk', 'test.txt'),
+    ])
+    ->send();
 ```
 
-### Custom Sender
+> [!NOTE]
+> `Attachment::fromData()` and `Attachment::fromStorage()` are not supported as they work with raw data.
 
-```php
-<?php
+### Attaching models to e-mails
 
-use Stackkit\LaravelDatabaseEmails\Email;
+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.
 
+```php
 Email::compose()
-    ->from('john@doe.com', 'John Doe');
+    ->model(User::find(1));
 ```
 
 ### Scheduling
 
 You may schedule an e-mail by calling `later` instead of `send`. You must provide a Carbon instance or a strtotime valid date.
 
 ```php
-<?php
-
-use Stackkit\LaravelDatabaseEmails\Email;
-
 Email::compose()
     ->later('+2 hours');
 ```
 
-### Encryption (Optional)
+### Queueing e-mails
+
+> [!IMPORTANT]
+> When queueing mail using the `queue` function, it is no longer necessary to schedule the `email:send` command.
 
-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.
+```php
+Email::compose()->queue();
 
-```text
-Without encryption
+// On a specific connection
+Email::compose()->queue(connection: 'sqs');
 
-7    bytes (label)
-16   bytes (recipient)
-20   bytes (subject)
-48   bytes (view name)
-116  bytes (variables)
-1874 bytes (e-mail content)
-4    bytes (attempts, sending, failed, encrypted)
-57   bytes (created_at, updated_at, deleted_at)
-... x 10.000 rows = ± 21.55 MB
+// On a specific queue
+Email::compose()->queue(queue: 'email-queue');
 
-With encryption the table size is ± 50.58 MB.
+// Delay (send mail in 10 minutes)
+Email::compose()->queue(delay: now()->addMinutes(10));
 ```
 
+If you need more flexibility, you may also pass your own job class:
 
-### Queueing e-mails
+```php
+Email::compose()->queue(jobClass: CustomSendEmailJob::class);
+```
 
-**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`.
+It could look like this:
 
 ```php
 <?php
 
-use Stackkit\LaravelDatabaseEmails\Email;
-
-Email::compose()
-    ->queue();
-
-// on a specific connection
-Email::compose()
-    ->queue('sqs');
+namespace App\Jobs;
 
-// on a specific queue
-Email::compose()
-    ->queue(null, 'email-queue');
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Stackkit\LaravelDatabaseEmails\SendEmailJob;
 
-// timeout (send mail in 10 minutes)
-Email::compose()
-    ->queue(null, null, now()->addMinutes(10));
+class CustomSendEmailJob extends SendEmailJob implements ShouldQueue
+{
+    // Define custom retries, backoff, etc...
+}
 ```
 
-### Test mode (Optional)
+### Test mode
 
 When enabled, all newly created e-mails will be sent to the specified test e-mail address. This is turned off by default.
 
+```dotenv
+DB_EMAILS_TESTING_ENABLED=true
+DB_EMAILS_TESTING_EMAIL=your-test-recipient@example.com
+```
+
 ### E-mails to send per minute
 
-To configure how many e-mails should be sent each command, please check the `limit` option. The default is `20` e-mails every command.
+To configure how many e-mails should be sent each command.
 
-### Send e-mails immediately (Optional)
+```dotenv
+DB_EMAILS_LIMIT=20
+```
+
+### Send e-mails immediately
 
 Useful during development when Laravel Scheduler is not running
 
 To enable, set the following environment variable:
 
-```
-LARAVEL_DATABASE_EMAILS_SEND_IMMEDIATELY=true
+```dotenv
+DB_EMAILS_IMMEDIATELY=true
 ```
 
 ### Pruning models
@@ -260,7 +237,7 @@ use Stackkit\LaravelDatabaseEmails\Email;
 
 $schedule->command('model:prune', [
     '--model' => [Email::class],
-])->everyMinute();
+])->daily();
 ```
 
 By default, e-mails are pruned when they are older than 6 months.