From 8c59bfcafb2522f971001ac4c2cd71b221f68160 Mon Sep 17 00:00:00 2001 From: Martijn van Nieuwenhoven Date: Thu, 4 Jul 2024 20:37:56 +0200 Subject: [PATCH] More docs --- .gitbook.yaml | 1 - README.md | 23 ++++++- config/emailviewer.php | 42 +++++++++++- docs/configuration.md | 66 +++++++++++++++++++ docs/installation.md | 27 ++++++++ docs/laravel-email-viewer.md | 17 +++++ docs/requirements.md | 2 + resources/views/layout/sidebar.blade.php | 2 +- routes/emailviewer.php | 14 ++-- src/Http/Controllers/BladeEmailController.php | 2 +- .../Controllers/JsonEmailControllerTest.php | 6 +- 11 files changed, 185 insertions(+), 17 deletions(-) create mode 100644 docs/laravel-email-viewer.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 1397eaa..c9876e8 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,4 +1,3 @@ root: ./docs/ structure: - readme: ./../README.md summary: ./SUMMARY.md diff --git a/README.md b/README.md index 33cfe38..490c539 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,22 @@ an email driver for your local or staging environment, you can inspect emails wi * Packed with a simple Blade UI and a Vue.js/JSON controller * Easily integrate in your existing application +## Usage + +Outgoing emails will be automatically copied to a local disk or table, but you can work with this package manually as well with the Emails facade: + +```php +get(); +``` + ## Quick start Run the composer install command from the terminal: @@ -29,7 +45,7 @@ composer require axyr/laravel-email-viewer Publish the database migration and configuration file: ```php - php artisan vendor:publish --provider="Axyr\EmailViewer\EmailViewerServiceProvider" +php artisan vendor:publish --provider="Axyr\EmailViewer\EmailViewerServiceProvider" ``` By default the package provides a set of routes for the Blade UI and the Vue UI. You can disabled them in the config file. @@ -40,10 +56,11 @@ You can access the Blade UI by visiting: https://your-host.tld/emails ``` -To send a test email the package provides a Test command: +To send a test email the package provides a simple Test command. +By default it will send to the laraval config value `mail.from.address` ```php -php artisan email-viewer:send-test +php artisan email-viewer:send-test --from=from@sender.tld --to=to@recipient.tld ``` For further information and customisation, visit our documentation page: diff --git a/config/emailviewer.php b/config/emailviewer.php index fd46776..305391d 100644 --- a/config/emailviewer.php +++ b/config/emailviewer.php @@ -1,13 +1,53 @@ env('EMAIL_VIEWER_DEFAULT', 'disk'), + + /* + * When this option is set to false, the package will not copy any emails. + */ 'enabled' => (bool)env('EMAIL_VIEWER_ENABLED', true), + + /* + * The PhpMimeMailParser uses the pecl mailparse extension. + * Replace this class if you want to use a customer mail parser. + */ 'parser' => \Axyr\EmailViewer\Parsers\PhpMimeMailParser::class, + + /* + * The EmailWriterListener listens to the MessageSending event + * and copies the email to the default storage. + */ 'listener' => \Axyr\EmailViewer\Listeners\EmailWriterListener::class, + + /* + * Disable this setting, if you don't want to use the default routes + * and instead use your own route setup. + */ 'routes-enabled' => true, - 'route-namespace' => 'emails', + + /* + * If you do want to use the default routes, + * but want a different prefix, you can adjust this value. + */ + 'route-prefix' => 'emails', + + /* + * The package controllers default items per page for the pagination results. + * If you want to use the shipped controllers, but a different default items per page, + * change this value. + */ 'default_pagination' => 25, + + /* + * The possible 'servers' where you can store a copy of all the outgoing emails. + * You can swap out the model and repository classes with your own implementations. + */ 'servers' => [ 'disk' => [ 'disk_name' => env('EMAIL_VIEWER_DISK', env('FILESYSTEM_DISK', 'local')), diff --git a/docs/configuration.md b/docs/configuration.md index a025a48..05c4175 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1 +1,67 @@ # Configuration + +```php + env('EMAIL_VIEWER_DEFAULT', 'disk'), + + /* + * When this option is set to false, the package will not copy any emails. + */ + 'enabled' => (bool)env('EMAIL_VIEWER_ENABLED', true), + + /* + * The PhpMimeMailParser uses the pecl mailparse extension. + * Replace this class if you want to use a customer mail parser. + */ + 'parser' => \Axyr\EmailViewer\Parsers\PhpMimeMailParser::class, + + /* + * The EmailWriterListener listens to the MessageSending event + * and copies the email to the default storage. + */ + 'listener' => \Axyr\EmailViewer\Listeners\EmailWriterListener::class, + + /* + * Disable this setting, if you don't want to use the default routes + * and instead use your own route setup. + */ + 'routes-enabled' => true, + + /* + * If you do want to use the default routes, + * but want a different prefix, you can adjust this value. + */ + 'route-prefix' => 'emails', + + /* + * The package controllers default items per page for the pagination results. + * If you want to use the shipped controllers, but a different default items per page, + * change this value. + */ + 'default_pagination' => 25, + + /* + * The possible 'servers' where you can store a copy of all the outgoing emails. + * You can swap out the model and repository classes with your own implementations. + */ + 'servers' => [ + 'disk' => [ + 'disk_name' => env('EMAIL_VIEWER_DISK', env('FILESYSTEM_DISK', 'local')), + 'model' => \Axyr\EmailViewer\Servers\Disk\Email::class, + 'repository' => \Axyr\EmailViewer\Servers\Disk\Repository::class, + ], + 'database' => [ + 'table_name' => 'email_viewer_emails', + 'model' => \Axyr\EmailViewer\Servers\Database\Email::class, + 'repository' => \Axyr\EmailViewer\Servers\Database\Repository::class, + ], + ], +]; +``` diff --git a/docs/installation.md b/docs/installation.md index 25267fe..0870881 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1 +1,28 @@ # Installation + +Run the composer install command from the terminal: + +```php +composer require axyr/laravel-email-viewer +``` + +Publish the database migration and configuration file: + +```php +php artisan vendor:publish --provider="Axyr\EmailViewer\EmailViewerServiceProvider" +``` + +By default the package provides a set of routes for the Blade UI and the Vue UI. You can disabled them in the config file. + +You can access the Blade UI by visiting: + +``` +https://your-host.tld/emails +``` + +To send a test email the package provides a simple Test command. +By default it will send to the laraval config value `mail.from.address` + +```php +php artisan email-viewer:send-test --from=from@sender.tld --to=to@recipient.tld +``` diff --git a/docs/laravel-email-viewer.md b/docs/laravel-email-viewer.md new file mode 100644 index 0000000..aac8f29 --- /dev/null +++ b/docs/laravel-email-viewer.md @@ -0,0 +1,17 @@ +# 📨 Laravel Email Viewer + +View and inspect all emails sent from your Laravel application. + +![](docs/img/mailboxes.png) + +Laravel Email Viewer is a package that allows you to view all emails sent from you application in the browser. This allows you to ensure your application has actually sent the mail. When using log as +an email driver for your local or staging environment, you can inspect emails without the need for external tools like Mailtrap or Mailhog, so emails never have to leave your server at all. + +[![Latest Version on Packagist](https://img.shields.io/packagist/v/axyr/laravel-email-viewer.svg?style=flat-square)](https://packagist.org/packages/axyr/laravel-email-viewer) [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/spatie/laravel-permission/run-tests-L8.yml?branch=main\&label=Tests)](https://github.com/axyr/laravel-email-viewer/actions?query=workflow%3ATests+branch%3Amain) + +## Key features + +* Log all application emails to a storage disk or database table +* Inspect HTML, attachments and email headers +* Packed with a simple Blade UI and a Vue.js/JSON controller +* Easily integrate in your existing application diff --git a/docs/requirements.md b/docs/requirements.md index 1fa9034..f468e29 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -1 +1,3 @@ # Requirements + +mailparse diff --git a/resources/views/layout/sidebar.blade.php b/resources/views/layout/sidebar.blade.php index 21513a9..4b8ab5f 100644 --- a/resources/views/layout/sidebar.blade.php +++ b/resources/views/layout/sidebar.blade.php @@ -1,7 +1,7 @@ @foreach($emails as $email) diff --git a/routes/emailviewer.php b/routes/emailviewer.php index d18fa13..0e1572b 100644 --- a/routes/emailviewer.php +++ b/routes/emailviewer.php @@ -4,12 +4,12 @@ use Axyr\EmailViewer\Http\Controllers\JsonEmailController; use Illuminate\Support\Facades\Route; -$routeNamespace = config('emailviewer.route-namespace'); +$routePrefix = config('emailviewer.route-prefix'); -Route::get($routeNamespace . '/json', [JsonEmailController::class, 'index'])->name($routeNamespace . '.json.index'); -Route::get($routeNamespace . '/{id}/json', [JsonEmailController::class, 'show'])->name($routeNamespace . '.json.show'); -Route::delete($routeNamespace . '/{id}/json', [JsonEmailController::class, 'destroy'])->name($routeNamespace . '.json.destroy'); +Route::get($routePrefix . '/json', [JsonEmailController::class, 'index'])->name($routePrefix . '.json.index'); +Route::get($routePrefix . '/{id}/json', [JsonEmailController::class, 'show'])->name($routePrefix . '.json.show'); +Route::delete($routePrefix . '/{id}/json', [JsonEmailController::class, 'destroy'])->name($routePrefix . '.json.destroy'); -Route::get($routeNamespace, [BladeEmailController::class, 'index'])->name($routeNamespace . '.index'); -Route::get($routeNamespace . '/{id}', [BladeEmailController::class, 'show'])->name($routeNamespace . '.show'); -Route::delete($routeNamespace . '/{id}', [BladeEmailController::class, 'destroy'])->name($routeNamespace . '.destroy'); +Route::get($routePrefix, [BladeEmailController::class, 'index'])->name($routePrefix . '.index'); +Route::get($routePrefix . '/{id}', [BladeEmailController::class, 'show'])->name($routePrefix . '.show'); +Route::delete($routePrefix . '/{id}', [BladeEmailController::class, 'destroy'])->name($routePrefix . '.destroy'); diff --git a/src/Http/Controllers/BladeEmailController.php b/src/Http/Controllers/BladeEmailController.php index f149bcd..72ec272 100644 --- a/src/Http/Controllers/BladeEmailController.php +++ b/src/Http/Controllers/BladeEmailController.php @@ -30,7 +30,7 @@ public function destroy(string|int $id): RedirectResponse { Emails::delete($id); - $routeNamespace = config('emailviewer.route-namespace'); + $routeNamespace = config('emailviewer.route-prefix'); return redirect(route($routeNamespace . '.index')); } diff --git a/tests/Http/Controllers/JsonEmailControllerTest.php b/tests/Http/Controllers/JsonEmailControllerTest.php index e332325..38da8d9 100644 --- a/tests/Http/Controllers/JsonEmailControllerTest.php +++ b/tests/Http/Controllers/JsonEmailControllerTest.php @@ -26,7 +26,7 @@ public function testListsPaginatedEmails(): void { config()->set('emailviewer.default_pagination', 3); - $routeNamespace = config('emailviewer.route-namespace'); + $routeNamespace = config('emailviewer.route-prefix'); for ($i = 0; $i < 6; $i++) { app(Repository::class)->create($this->emailContent . $i); @@ -41,7 +41,7 @@ public function testListsPaginatedEmails(): void public function testShowsAnEmail(): void { - $routeNamespace = config('emailviewer.route-namespace'); + $routeNamespace = config('emailviewer.route-prefix'); $email = app(Repository::class)->create($this->emailContent); @@ -52,7 +52,7 @@ public function testShowsAnEmail(): void public function testDeletesAnEmail(): void { - $routeNamespace = config('emailviewer.route-namespace'); + $routeNamespace = config('emailviewer.route-prefix'); $email = app(Repository::class)->create($this->emailContent);