Email Preview for Laravel

Don't use! This package is retired: it broke after Laravel v8.33 was released. Read the details

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.

MailView list of template screenshot MailView render template screenshot MailView render template screenshot 2

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.

__torchlight-block-[b0b95368-a8b0-4f4a-bf1a-69fb46847031]__

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.

__torchlight-block-[9e5c369a-7403-4f2e-88a1-521962a88bb0]__

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. MailView screenshot with show code open

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 *

__torchlight-block-[1b34cca9-b136-4b75-bb1b-cadc1124d741]__

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.

__torchlight-block-[854eb8b8-00ee-4f34-98fe-bfb9272bc12c]__

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.

__torchlight-block-[435d95d9-0e09-4579-a8cf-74a2a7f1b33c]__

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.

Email sent confirmation

Configuration

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

__torchlight-block-[728c8b8b-5edb-4101-a309-2957aa6551bd]__

Here is the default configuration that ships with the package.

__torchlight-block-[c0757b96-c7ac-4595-a532-6d1ed6cd86a6]__

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.