├── README.md
├── composer.json
├── config
    └── mail-export.php
└── src
    ├── Concerns
        └── Exportable.php
    ├── Contracts
        └── ShouldExport.php
    ├── Events
        └── MessageStored.php
    ├── Listeners
        └── ExportMessage.php
    ├── MailExportServiceProvider.php
    ├── Providers
        └── EventServiceProvider.php
    └── StorageOptions.php


/README.md:
--------------------------------------------------------------------------------
  1 | # Laravel Mail Export
  2 | 
  3 | [![Latest Version on Packagist](https://img.shields.io/packagist/v/pod-point/laravel-mail-export.svg?style=flat-square)](https://packagist.org/packages/pod-point/laravel-mail-export)
  4 | [![tests](https://github.com/Pod-Point/laravel-mail-export/actions/workflows/run-tests.yml/badge.svg?branch=2.x)](https://github.com/Pod-Point/laravel-mail-export/actions/workflows/run-tests.yml)
  5 | [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
  6 | [![Total Downloads](https://img.shields.io/packagist/dt/pod-point/laravel-mail-export.svg?style=flat-square)](https://packagist.org/packages/pod-point/laravel-mail-export)
  7 | 
  8 | This package can export any mail sent with Laravel's `Mailable` class to any desired filesystem disk and path as a `.eml` file.
  9 | 
 10 | This can be useful when wanting to store emails sent for archive purposes.
 11 | 
 12 | ## Installation
 13 | 
 14 | You can install the package via composer:
 15 | 
 16 | For Laravel 9.x, 10.x, 11.x (requires PHP version 8.2 or higher)
 17 | 
 18 | ```bash
 19 | composer require pod-point/laravel-mail-export
 20 | ```
 21 | 
 22 | For Laravel 7.x and 8.x
 23 | 
 24 | ```bash
 25 | composer require pod-point/laravel-mail-export:^1.0
 26 | ```
 27 | 
 28 | For Laravel 5.x and 6.x
 29 | 
 30 | ```bash
 31 | composer require pod-point/laravel-mail-export:^0.1
 32 | ```
 33 | 
 34 | ### Publishing the config file
 35 | 
 36 | The configuration for this package comes with some sensible values but you can optionally publish the config file with:
 37 | 
 38 | ```bash
 39 | php artisan vendor:publish --provider="PodPoint\MailExport\MailExportServiceProvider"
 40 | ```
 41 | 
 42 | You will be able to specify:
 43 | 
 44 | * `enabled`: whether this package is enabled or not. Once installed, it's enabled by default but the `MAIL_EXPORT` environment variable can be used to configure this.
 45 | * `disk`: which disk to use by default. `null` will use the default disk from your application filesystem.
 46 | * `path`: the default path, within the configured disk, where mail will be exported.
 47 | 
 48 | See our [`config/mail-export.php`](config/mail-export.php) for more details.
 49 | 
 50 | ## Usage
 51 | 
 52 | Simply add the `Exportable` trait and the `ShouldExport` interface to any Mailable class that you want to persist into any storage disk.
 53 | 
 54 | ```php
 55 | <?php
 56 | 
 57 | namespace App\Mail;
 58 | 
 59 | use Illuminate\Mail\Mailable;
 60 | use PodPoint\MailExport\Concerns\Exportable;
 61 | use PodPoint\MailExport\Contracts\ShouldExport;
 62 | 
 63 | class OrderShipped extends Mailable implements ShouldExport
 64 | {
 65 |     use Exportable;
 66 | 
 67 |     // ...
 68 | }
 69 | ```
 70 | 
 71 | This will use the default filesystem `disk` and `path` from the configuration and will also generate a unique `filename` for you.
 72 | 
 73 | The default filename is using a timestamp, the mail recipients, the subject and will look like so:
 74 | 
 75 | ```
 76 | 2021_03_26_150142_jane_at_example_com_this_is_the_subject.eml
 77 | ```
 78 | 
 79 | You can also specify the `disk`, `path` or `filename` to use for a specific Mailable using properties:
 80 | 
 81 | ```php
 82 | <?php
 83 | 
 84 | namespace App\Mail;
 85 | 
 86 | use Illuminate\Mail\Mailable;
 87 | use PodPoint\MailExport\Concerns\Exportable;
 88 | use PodPoint\MailExport\Contracts\ShouldExport;
 89 | 
 90 | class OrderShipped extends Mailable implements ShouldExport
 91 | {
 92 |     use Exportable;
 93 | 
 94 |     public $exportDisk = 'some_disk';
 95 | 
 96 |     public $exportPath = 'some_path';
 97 | 
 98 |     public $exportFilename = 'some_filename';
 99 | 
100 |     // ...
101 | }
102 | ```
103 | 
104 | You can also use methods if you need more flexibility:
105 | 
106 | ```php
107 | <?php
108 | 
109 | namespace App\Mail;
110 | 
111 | use Illuminate\Mail\Mailable;
112 | use PodPoint\MailExport\Concerns\Exportable;
113 | use PodPoint\MailExport\Contracts\ShouldExport;
114 | 
115 | class OrderShipped extends Mailable implements ShouldExport
116 | {
117 |     use Exportable;
118 | 
119 |     // ...
120 | 
121 |     public function exportDisk(): string
122 |     {
123 |         return 'some_disk';
124 |     }
125 | 
126 |     public function exportPath(): string
127 |     {
128 |         return 'some_path';
129 |     }
130 | 
131 |     public function exportFilename(): string
132 |     {
133 |         return 'some_filename';
134 |     }
135 | }
136 | ```
137 | 
138 | Then you can keep using your `Mailable` as usual:
139 | 
140 | ```php
141 | Mail::to($request->user())->send(new OrderShipped($order));
142 | ```
143 | 
144 | Even with Notifications too:
145 | 
146 | ```php
147 | <?php
148 | 
149 | namespace App\Notifications;
150 | 
151 | use App\Mail\OrderShipped as Mailable;
152 | use Illuminate\Notifications\Notification;
153 | 
154 | class OrderShipped extends Notification
155 | {
156 |     // ...
157 | 
158 |     public function toMail($notifiable)
159 |     {
160 |         return (new Mailable($this->order))->to($notifiable->email);
161 |     }
162 | }
163 | ```
164 | 
165 | ## Testing
166 | 
167 | Run the tests with:
168 | 
169 | ```bash
170 | composer test
171 | ```
172 | 
173 | ## Changelog
174 | 
175 | Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
176 | 
177 | ## Contributing
178 | 
179 | Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
180 | 
181 | ## Credits
182 | 
183 | - [themsaid](https://github.com/themsaid) and Spatie's [laravel-mail-preview](https://github.com/spatie/laravel-mail-preview) for some inspiration
184 | - [Laravel Package Development](https://laravelpackage.com) documentation by [John Braun](https://github.com/Jhnbrn90)
185 | - [Pod Point](https://github.com/pod-point)
186 | - [All Contributors](https://github.com/pod-point/laravel-mail-export/graphs/contributors)
187 | 
188 | ## License
189 | 
190 | The MIT License (MIT). Please see [License File](LICENCE.md) for more information.
191 | 
192 | ---
193 | 
194 | <img src="https://d3h256n3bzippp.cloudfront.net/pod-point-logo.svg" align="right" />
195 | 
196 | Travel shouldn't damage the earth 🌍
197 | 
198 | Made with ❤️&nbsp;&nbsp;at [Pod Point](https://pod-point.com)
199 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "pod-point/laravel-mail-export",
 3 |     "description": "A mailable trait to export mails to a storage disk once being sent",
 4 |     "keywords": ["laravel", "mail", "storage", "archive", "backup"],
 5 |     "homepage": "https://github.com/pod-point/laravel-mail-export",
 6 |     "license": "MIT",
 7 |     "authors": [
 8 |         {
 9 |             "name": "Pod Point Software Team",
10 |             "email": "software@pod-point.com"
11 |         }
12 |     ],
13 |     "require": {
14 |         "php": "^8.1",
15 |         "illuminate/filesystem": "^9.0|^10.0|^11.0",
16 |         "illuminate/mail": "^9.0|^10.0|^11.0",
17 |         "illuminate/support": "^9.0|^10.0|^11.0",
18 |         "nesbot/carbon": "^2.0"
19 |     },
20 |     "require-dev": {
21 |         "orchestra/testbench": "^7.0|^8.0|^9.0"
22 |     },
23 |     "autoload": {
24 |         "psr-4": {
25 |             "PodPoint\\MailExport\\": "src"
26 |         }
27 |     },
28 |     "autoload-dev": {
29 |         "psr-4": {
30 |             "PodPoint\\MailExport\\Tests\\": "tests"
31 |         }
32 |     },
33 |     "extra": {
34 |         "laravel": {
35 |             "providers": [
36 |                 "PodPoint\\MailExport\\MailExportServiceProvider"
37 |             ]
38 |         }
39 |     },
40 |     "scripts": {
41 |         "test": "vendor/bin/phpunit --colors=always",
42 |         "test-coverage": "vendor/bin/phpunit --coverage-html coverage"
43 |     },
44 |     "minimum-stability": "dev",
45 |     "prefer-stable": true,
46 |     "config": {
47 |         "sort-packages": true
48 |     }
49 | }
50 | 


--------------------------------------------------------------------------------
/config/mail-export.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | return [
 4 | 
 5 |     /*
 6 |     |--------------------------------------------------------------------------
 7 |     | Main switch
 8 |     |--------------------------------------------------------------------------
 9 |     |
10 |     | This is where you can completely enable or disable the package export
11 |     | functionality. If disabled, this will only prepare the export when
12 |     | it will not actually store it anywhere. Does what's on the tin.
13 |     |
14 |     */
15 | 
16 |     'enabled' => env('MAIL_EXPORT', true),
17 | 
18 |     /*
19 |     |--------------------------------------------------------------------------
20 |     | Default Filesystem Disk
21 |     |--------------------------------------------------------------------------
22 |     |
23 |     | Here you may specify the default filesystem disk that should be used
24 |     | by the package in order to export a copy of your mail sent out by
25 |     | the framework. Make sure your filesystem disks are configured!
26 |     |
27 |     | You can set this to `null` and we will automatically use the default
28 |     | disk configured for your application.
29 |     |
30 |     */
31 | 
32 |     'disk' => null,
33 | 
34 |     /*
35 |     |--------------------------------------------------------------------------
36 |     | Default Filesystem Path
37 |     |--------------------------------------------------------------------------
38 |     |
39 |     | Here you may specify the default filesystem path that should be used
40 |     | by the package when exporting a mail. This can also be changed at
41 |     | a Mailable or Message level. Make sure to check our README.md.
42 |     |
43 |     */
44 | 
45 |     'path' => 'email-exports',
46 | 
47 | ];
48 | 


--------------------------------------------------------------------------------
/src/Concerns/Exportable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PodPoint\MailExport\Concerns;
 4 | 
 5 | use Illuminate\Mail\Mailable;
 6 | use PodPoint\MailExport\Contracts\ShouldExport;
 7 | use PodPoint\MailExport\StorageOptions;
 8 | 
 9 | /**
10 |  * @mixin Mailable
11 |  */
12 | trait Exportable
13 | {
14 |     /**
15 |      * @inheritDoc
16 |      */
17 |     public function send($mailer)
18 |     {
19 |         $this->withSymfonyMessage(function ($message) {
20 |             if (! $this instanceof ShouldExport) {
21 |                 return;
22 |             }
23 | 
24 |             $message->_storageOptions = new StorageOptions($message, [
25 |                 'disk' => $this->exportOption('exportDisk'),
26 |                 'path' => $this->exportOption('exportPath'),
27 |                 'filename' => $this->exportOption('exportFilename'),
28 |             ]);
29 |         });
30 | 
31 |         parent::send($mailer);
32 |     }
33 | 
34 |     /**
35 |      * Tries to resolve storage options from an optional method and property.
36 |      *
37 |      * @param  string  $key
38 |      * @return string|null
39 |      */
40 |     private function exportOption(string $key): ?string
41 |     {
42 |         if (method_exists($this, $key)) {
43 |             return $this->$key();
44 |         }
45 | 
46 |         return property_exists($this, $key) ? $this->$key : null;
47 |     }
48 | }
49 | 


--------------------------------------------------------------------------------
/src/Contracts/ShouldExport.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | namespace PodPoint\MailExport\Contracts;
4 | 
5 | interface ShouldExport
6 | {
7 |     //
8 | }
9 | 


--------------------------------------------------------------------------------
/src/Events/MessageStored.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PodPoint\MailExport\Events;
 4 | 
 5 | use Illuminate\Foundation\Events\Dispatchable;
 6 | use PodPoint\MailExport\StorageOptions;
 7 | use Symfony\Component\Mime\Email;
 8 | 
 9 | class MessageStored
10 | {
11 |     use Dispatchable;
12 | 
13 |     /**
14 |      * The message instance.
15 |      *
16 |      * @var \Symfony\Component\Mime\Email
17 |      */
18 |     public $message;
19 | 
20 |     /**
21 |      * The filesystem storage options used to store the message including
22 |      * the disk, the path and the filename with its extension.
23 |      *
24 |      * @var \PodPoint\MailExport\StorageOptions
25 |      */
26 |     public $storageOptions;
27 | 
28 |     /**
29 |      * Create a new event instance.
30 |      *
31 |      * @param  Email  $message
32 |      * @param  StorageOptions  $storageOptions
33 |      * @return void
34 |      */
35 |     public function __construct(Email $message, StorageOptions $storageOptions)
36 |     {
37 |         $this->message = $message;
38 |         $this->storageOptions = $storageOptions;
39 |     }
40 | }
41 | 


--------------------------------------------------------------------------------
/src/Listeners/ExportMessage.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PodPoint\MailExport\Listeners;
 4 | 
 5 | use Illuminate\Contracts\Filesystem\Factory;
 6 | use Illuminate\Mail\Events\MessageSent;
 7 | use PodPoint\MailExport\Events\MessageStored;
 8 | use PodPoint\MailExport\StorageOptions;
 9 | use Symfony\Component\Mime\Email;
10 | 
11 | class ExportMessage
12 | {
13 |     /**
14 |      * @var \Illuminate\Contracts\Filesystem\Factory
15 |      */
16 |     protected $filesystem;
17 | 
18 |     /**
19 |      * Create a new listener instance.
20 |      *
21 |      * @param  Factory  $filesystem
22 |      */
23 |     public function __construct(Factory $filesystem)
24 |     {
25 |         $this->filesystem = $filesystem;
26 |     }
27 | 
28 |     /**
29 |      * Handles the Event when it happens while listening.
30 |      *
31 |      * @param  MessageSent  $event
32 |      */
33 |     public function handle(MessageSent $event)
34 |     {
35 |         if ($this->shouldStoreMessage($event->message)) {
36 |             $this->storeMessage($event->message);
37 |         }
38 |     }
39 | 
40 |     /**
41 |      * Finds out if whether we should store the mail or not.
42 |      *
43 |      * @return bool
44 |      */
45 |     protected function shouldStoreMessage(Email $message): bool
46 |     {
47 |         return property_exists($message, '_storageOptions')
48 |             && config('mail-export.enabled', false);
49 |     }
50 | 
51 |     /**
52 |      * Actually stores the stringified version of the \Symfony\Component\Mime\Email
53 |      * including headers, recipients, subject and body onto the filesystem disk.
54 |      *
55 |      * @return void
56 |      */
57 |     private function storeMessage(Email $message)
58 |     {
59 |         /** @var StorageOptions $storageOptions */
60 |         $storageOptions = $message->_storageOptions;
61 | 
62 |         $this->filesystem
63 |             ->disk($storageOptions->disk)
64 |             ->put($storageOptions->fullpath(), $message->toString(), [
65 |                 'mimetype' => $storageOptions::MIME_TYPE,
66 |             ]);
67 | 
68 |         event(new MessageStored($message, $storageOptions));
69 |     }
70 | }
71 | 


--------------------------------------------------------------------------------
/src/MailExportServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PodPoint\MailExport;
 4 | 
 5 | use Illuminate\Support\ServiceProvider;
 6 | use PodPoint\MailExport\Providers\EventServiceProvider;
 7 | 
 8 | class MailExportServiceProvider extends ServiceProvider
 9 | {
10 |     /**
11 |      * Register the service provider.
12 |      *
13 |      * @return void
14 |      */
15 |     public function register()
16 |     {
17 |         $this->mergeConfigFrom(__DIR__.'/../config/mail-export.php', 'mail-export');
18 | 
19 |         $this->app->register(EventServiceProvider::class);
20 |     }
21 | 
22 |     /**
23 |      * Bootstrap any application services.
24 |      *
25 |      * @return void
26 |      */
27 |     public function boot()
28 |     {
29 |         if ($this->app->runningInConsole()) {
30 |             $this->publishes([
31 |                 __DIR__.'/../config/mail-export.php' => config_path('mail-export.php'),
32 |             ]);
33 |         }
34 |     }
35 | }
36 | 


--------------------------------------------------------------------------------
/src/Providers/EventServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace PodPoint\MailExport\Providers;
 4 | 
 5 | use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
 6 | use Illuminate\Mail\Events\MessageSent;
 7 | use PodPoint\MailExport\Listeners\ExportMessage;
 8 | 
 9 | class EventServiceProvider extends ServiceProvider
10 | {
11 |     /**
12 |      * The event handler mappings for the package.
13 |      *
14 |      * @var array
15 |      */
16 |     protected $listen = [
17 |         MessageSent::class => [
18 |             ExportMessage::class,
19 |         ],
20 |     ];
21 | }
22 | 


--------------------------------------------------------------------------------
/src/StorageOptions.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace PodPoint\MailExport;
  4 | 
  5 | use Carbon\Carbon;
  6 | use Illuminate\Support\Arr;
  7 | use Illuminate\Support\Str;
  8 | use Symfony\Component\Mime\Email;
  9 | 
 10 | /**
 11 |  * Data transfer object responsible for holding
 12 |  * storage information when exporting a mail.
 13 |  */
 14 | class StorageOptions
 15 | {
 16 |     const EXTENSION = 'eml';
 17 |     const MIME_TYPE = 'message/rfc822';
 18 | 
 19 |     /**
 20 |      * @var string
 21 |      */
 22 |     public $disk;
 23 | 
 24 |     /**
 25 |      * @var string
 26 |      */
 27 |     public $path;
 28 | 
 29 |     /**
 30 |      * @var string
 31 |      */
 32 |     public $filename;
 33 | 
 34 |     /**
 35 |      * @var \Symfony\Component\Mime\Email
 36 |      */
 37 |     public $message;
 38 | 
 39 |     /**
 40 |      * Declares the storage options for a specific \Symfony\Component\Mime\Email.
 41 |      * The only properties allowed are 'disk', 'path' and 'filename'. They all
 42 |      * are obviously optional.
 43 |      *
 44 |      * @param  Email  $message
 45 |      * @param  array  $properties
 46 |      */
 47 |     public function __construct(Email $message, array $properties = [])
 48 |     {
 49 |         $this->message = $message;
 50 | 
 51 |         $properties = Arr::only($properties, ['disk', 'path', 'filename']);
 52 | 
 53 |         foreach ($properties as $propertyName => $propertyValue) {
 54 |             $default = 'default'.Str::studly($propertyName);
 55 |             $this->$propertyName = $propertyValue ?: $this->$default();
 56 |         }
 57 |     }
 58 | 
 59 |     /**
 60 |      * Build the default storage disk using the config if none is provided by the developer.
 61 |      *
 62 |      * @return string
 63 |      */
 64 |     private function defaultDisk(): string
 65 |     {
 66 |         return config('mail-export.disk') ?: config('filesystems.default');
 67 |     }
 68 | 
 69 |     /**
 70 |      * Build the default storage path using the config if none is provided by the developer.
 71 |      *
 72 |      * @return string
 73 |      */
 74 |     private function defaultPath(): string
 75 |     {
 76 |         return config('mail-export.path');
 77 |     }
 78 | 
 79 |     /**
 80 |      * Build some default value for the filename of the message we're about to store
 81 |      * so this can be used if none is provided by the developer.
 82 |      *
 83 |      * @return string
 84 |      */
 85 |     private function defaultFilename(): string
 86 |     {
 87 |         /** @var \Symfony\Component\Mime\Address[] */
 88 |         $recipients = $this->message->getTo();
 89 | 
 90 |         $to = ! empty($recipients)
 91 |             ? str_replace(['@', '.'], ['_at_', '_'], $recipients[0]->getAddress()).'_'
 92 |             : '';
 93 | 
 94 |         $subject = $this->message->getSubject();
 95 | 
 96 |         $timestamp = Carbon::now()->format('Y_m_d_His');
 97 | 
 98 |         return Str::slug("{$timestamp}_{$to}{$subject}", '_');
 99 |     }
100 | 
101 |     /**
102 |      * Builds the full path we will store the file onto the disk.
103 |      *
104 |      * @return string
105 |      */
106 |     public function fullpath(): string
107 |     {
108 |         return "{$this->path}/{$this->filename}.".self::EXTENSION;
109 |     }
110 | 
111 |     /**
112 |      * Build some array representation of that data transfer object.
113 |      *
114 |      * @return array
115 |      */
116 |     public function toArray(): array
117 |     {
118 |         return [
119 |             'disk' => $this->disk,
120 |             'path' => $this->path,
121 |             'filename' => $this->filename,
122 |             'extension' => self::EXTENSION,
123 |             'fullpath' => $this->fullpath(),
124 |         ];
125 |     }
126 | }
127 | 


--------------------------------------------------------------------------------