Email Preview for Laravel

This package lets you preview how your emails look by visiting a special URL that renders them. The goal is to create a fake situation (create dummy user with orders for instance) to help you design the email templates.

This package is heavily inspired by Rails ActiveMailer Preview and the mail view name is an homage to the original gem.

Today, you can already return a mailable from a controller to preview its HTML but you don't get the subject or attachments details. You will also have to protect the route, create a list and so on. This package takes care of that for you.

Road to 1.0 release

This is the very first release of this package. I'm taking it 0.1 in case I missed something really bad. I'd love to get feedback and fix the things that aren't ideal but I want to get the 1.0.0 tagged soon.

Another thing I want to figure out is the version of Laravel and PHP to maintain. I'm hoping to get this package working all the way down to 5.3, when Mailable were introduced. I also intend to maintain PHP 5.6 if nothing is blocking.

Installation

Install the package via composer.

1composer require julienbourdeau/laravel-mail-view --dev

Usage

Getting Started

First, create Class in tests/MailView directory. We'll create one method per scenario, create some dummy data and return a Mailable.

Because you're meant to refresh this page a lot while developing the email template, it's recommended to avoid persisting data to the database. This is not always possible, if you need to create data (typically when an ID is required), use the After hooks to clean up after yourself.

 1<?php
 2 
 3namespace Tests\MailView;
 4 
 5use App\Mail\WelcomeNewUser; // <-- Mailable class
 6 
 7class OnboardingPreview
 8{
 9    public function welcomeNewUser()
10    {
11        $user = new User([
12            'email' => '[email protected]',
13            'name' => 'Julien Bourdeau',
14        ]);
15 
16        return new WelcomeNewUser($user);
17    }
18}

Once your first example is ready, head over example.com/mail_view to see it listed. All public methods are listed here and are expected to be valid example. Valid means it returns a Mailable. If you want to create helper methods, make sure they're private or protected.

In case you want to see how this email was generated, the Preview method code is available right from your browser.

Comments

Coming up with a very descriptive name is not always easy. You can add a docblock to your method and it will be used as a description of the preview.

Note: It only support in one line or at least without extra *

 1<?php
 2 
 3namespace Tests\MailView;
 4 
 5class OnboardingPreview
 6{
 7    /** Email sent to every new user, default version */
 8    public function welcomeNewUser()
 9    {
10        //
11    }
12 
13    /** Email sent to new user with special notice when they skipped onboarding demo
14        This comment is multi line and will render fine. */
15    public function welcomeNewUserSkippedDemo()
16    {
17        //
18    }
19 
20    /**
21     * This comment is multi line
22     * but all * on the left will be rendered
23     */
24    public function nope()
25    {
26        //
27    }
28}

Hooks

When generating a preview, you might have to save data. Typically, if your working with relationships, or if the mailable is reaching for something directly from the database, that was not passed in as an argument. In this case, the way is to use the after hooks to delete the data and not pollute your environment.

For example, if your preview method is called orderConfirmation, the package will execute afterOrderConfirmation (if it exists). After all preview it will also execute afterAll (if it exists). Note that those methods should be protected.

 1<?php
 2 
 3namespace Tests\MailView;
 4 
 5use App\Mail\Admin\NewUser; // <-- Mailable class
 6 
 7class OnboardingPreview
 8{
 9    public function welcomeNewUser()
10    {
11        $this->user = User::create([
12            'email' => '[email protected]',
13            'name' => 'Julien Bourdeau',
14        ]);
15 
16        return new WelcomeNewUser($this->user);
17    }
18 
19    public function newUserAdminNotification()
20    {
21        $this->user = User::create([
22            'email' => '[email protected]',
23            'name' => 'Julien Bourdeau',
24        ]);
25 
26        $this->history = UserHistory::create([
27            'label' => 'Created Account',
28            'timestamp' => Carbon::today()
29        ]);
30 
31        return new NewUser($this->user);
32    }
33 
34    // Only run after rendering newUserAdminNotification()
35    protected function afterNewUserAdminNotification()
36    {
37        $this->history->delete()
38    }
39 
40    // Run after any method rendering preview
41    protected function afterAll()
42    {
43        $this->user->delete();
44    }
45}

Accessing Previews

By default, previews are only visible if the app environment is set to local.

You may want to let your team access the previews from your staging environement, or maybe if your prod, if the user is an admin. In this case, you'll need to override the mail_view gate. If you don't know where to put it, I'd recommend putting it in the boot method of your AuthServiceProvider.

1\Gate::define('mail_view', function (User $user) {
2    return app()->environment(['local', 'staging'] || $user->isSuperAdmin();
3});

Sending preview emails

You may want to send those emails to see them in your phone or your actual email client. In this case, you can either send them all with one button or select the one you to send. The email will be sent to the logged in user email address if there is one, or the to address defined in the package configuration.

Configuration

If you want to override the default configuration, publish the config file via artisan. This will create the config/mail-view.php.

1php artisan vendor:publish --provider="Julienbourdeau\RouteUsage\RouteUsageServiceProvider" --tag=config

Here is the default configuration that ships with the package.

 1<?php
 2 
 3return [
 4 
 5    'url_prefix' => '/mail_view',
 6 
 7    'dir' => 'tests/MailView',
 8 
 9    'namespace' => 'Tests\MailView',
10 
11    'to' => '[email protected]',
12 
13];

Changing URL prefix

By default, all pages are prefixed by /mail_view. If you already use this route for something else, or simply because you don't like it, you can override the url_prefix configuration.

Changing default directory

By default, all preview classes are located in tests/MailView. If you want to change it, you need to update the dir configuration as well as the namespace configuration. They are both needed in order to find your Preview classes.

Setting email address

When sending emails, this pacakge will try to find the email of the logged in user and will default to the mail-view.to configuration if not found.