Mailbase Laravel Package

Getting Started

composer require tkeer/mailbase

• Laravel <5.5: register Tkeer\Mailbase\MailbaseServiceProvider in config/app.php.
• Publish the config: php artisan vendor:publish --provider="Tkeer\Mailbase\MailbaseServiceProvider" (or --tag=mailbase).
• Run migrations so the mailbase_emails table exists: php artisan migrate (confirm the provider loads the package migration; some versions require publishing first).
• Point Laravel's mail transport at the package. On Laravel ≤6: MAIL_DRIVER=mailbase in .env. On Laravel ≥7: define a mailer in config/mail.php with ['transport' => 'mailbase'] and set MAIL_MAILER=mailbase.
• Open /mailbase in the browser (default prefix; overridable in config/mailbase.php).

First use case: replace log/array mail during local development. Send mail as you normally would —

Mail::to($user->email)->send(new WelcomeMail($user));

— then open /mailbase and you'll see the rendered message in a list, without spamming a real inbox or paying for Mailtrap.

Implementation Patterns

Scope the driver to local/testing only. Keep smtp (or a real ESP) in production. The cleanest pattern is to set MAIL_MAILER=mailbase in .env.local and let .env for prod carry smtp. Never bake mailbase into a shared .env.example.

Laravel 7+ mailer wiring. Newer Laravel versions use named mailers, not a single MAIL_DRIVER. Add:

'mailers' => [
    'mailbase' => ['transport' => 'mailbase'],
    // ...
],

and set MAIL_MAILER=mailbase. If the package only ships a Mail::extend('mailbase', ...)-style hook, you may need to call it from a service provider — check vendor/tkeer/mailbase/src before wiring.

Queued mail and notifications. Anything routed through the Mail facade is caught automatically, including Notifiable mail notifications and Mail::raw(). With QUEUE_CONNECTION=sync locally, the email appears immediately after the request; with database/redis, run php artisan queue:work and the stored row appears when the job runs. This makes mailbase a decent smoke-test for "did the mailable actually build?"

Testing stays on Mail::fake(). Do not assert against mailbase_emails in feature tests — use Mail::assertSent(WelcomeMail::class). Keep mailbase for eyeballing rendered HTML and headers; it is a viewer, not a test harness. If you do want to inspect stored rows in a test, query the table directly:

$this->assertDatabaseHas('mailbase_emails', ['subject' => 'Welcome']);

Custom route and middleware. In config/mailbase.php change the route.prefix and add middleware (e.g. ['web', 'auth']) so the viewer isn't wide-open on a team LAN or staging box. This is the main extension point most teams touch.

Cleanup in your reset flow. The table grows fast once seeders and test emails fire. Add DB::table('mailbase_emails')->truncate() to your migrate:fresh seed run, or schedule a small artisan command. Treat it like storage/logs/laravel.log — disposable.

Gotchas and Tips

• Maintenance risk. The package predates Laravel 7's Symfony Mailer rewrite. On modern Laravel you may hit InvalidArgumentException: Unsupported mail transport [mailbase]. Confirm registration in vendor/; if it silently no-ops, fork it or register the transport yourself in a small service provider.
• MAIL_DRIVER vs MAIL_MAILER. Laravel 7 renamed the env key. Copying an old README is the #1 reason "nothing shows up."
• Config cache. After editing config/mailbase.php or config/mail.php, run php artisan config:clear. If you're switching environments, config:cache in prod must be re-run or you'll ship a cache that still points at mailbase.
• Missing table = silent mail loss. Because you replaced the driver, a failed insert means the email is not sent anywhere else. Run php artisan migrate and verify mailbase_emails exists before flipping the env var.
• Route collisions. Routes register on web middleware by default. A /{any} catch-all or an existing mailbase named route can shadow or be shadowed — check php artisan route:list | grep -i mailbase.
• Rendering is not a mailbox. HTML is stored raw; relative asset URLs won't resolve and dark-mode / Gmail clipping behave differently. For anything pixel- or attachment-heavy, prefer Mailpit or MailHog.
• Storage as raw MIME. Messages (including base64 attachments) are stored whole in the DB. A few large attachments will noticeably bloat your local SQLite/MySQL.
• Queued failures. Under async queues, a failed DB insert in the worker means the email never appears and no exception bubbles to your request. Check storage/logs/laravel.log and failed_jobs.
• Forking is cheap. The codebase is small. Adding a tenant_id column, search, or a Vue/Blade filter is often faster than working around the defaults — that's the intended extension point for a package this size.