Tuxedo Laravel Package

Getting Started

1. Install the package:

   composer require tomirons/tuxedo
   

   Laravel 5.5+ will auto-register the service provider. On older 5.x releases add TomIrons\Tuxedo\TuxedoServiceProvider to config/app.php and register the Tuxedo facade if you plan to use the fluent send API.

2. Where to look first: start with the package's src/ – the base class (typically Tuxedo extends Mailable) is the one file you actually extend. The views that ship with it are plain Blade templates; anything you don't override is inherited.

3. First use case – send a welcome email:

   // app/Mail/WelcomeEmail.php - typically created by hand, not artisan make:mail
   namespace App\Mail;
   
   use TomIrons\Tuxedo\Tuxedo;
   
   class WelcomeEmail extends Tuxedo
   {
       public $user;
   
       public function __construct($user)
       {
           $this->user = $user;
       }
   
       public function subject()
       {
           return 'Welcome to ' . config('app.name');
       }
   
       public function template()
       {
           return 'emails.welcome'; // your Blade view
       }
   }
   

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

   That's the entire day-one loop: extend the base class, give it a subject and a view, send it. Everything else the package adds is sugar layered on top of Laravel's Mailable.

Implementation Patterns

• One class per transactional email. Treat each email like a job class: WelcomeEmail, PasswordResetEmail, InvoicePaidEmail. Keep the data you need on public properties and pass it through the constructor. This is what makes the Mail::to(...)->send(...) call sites read cleanly and makes tests trivial.

• Separate "system" mail from marketing mail. Tuxedo is aimed at transactional mail – password resets, receipts, notifications. Don't repurpose it for newsletters or bulk sends; that's a different tooling problem (and a different deliverability conversation).

• Fluent recipient chaining:

   Tuxedo::to($user->email)
       ->with(['user' => $user, 'invoice' => $invoice])
       ->send(new InvoicePaidEmail);
  

  The fluent facade is the package's main ergonomic win – useful for one-off admin or console-driven sends where you don't want to construct the mailable fully.

• Data via public properties, not with(). The idiomatic pattern in Laravel mailables (and Tuxedo follows it) is to expose data on public properties and reference them directly in the Blade view. Reserve with() for one-off extras.

• Reuse a shared layout. Put a single emails.layouts.master Blade file in resources/views and have each transactional template @extends it. Tuxedo doesn't ship a polished template – you're expected to bring your own branding. This is the fastest way to keep a consistent look across all transactional emails.

• Queue by default. Add implements ShouldQueue to the class (or use Mail::queue / Mail::later) so a slow SMTP server doesn't block a password reset. php artisan queue:work must be running; note this in your deploy checklist.

• Test with Mail::fake(). Because Tuxedo classes are still mailables, Mail::fake() + Mail::assertSent(WelcomeEmail::class, function ($mail) { ... }) works out of the box. Assert on data, not on rendered HTML – rendering is the fragile part.

• Local preview via mailtrap or log driver. Set MAIL_DRIVER=log in local .env and inspect the rendered HTML in storage/logs/laravel.log. Combine with a route that returns (new WelcomeEmail($user))->render() for a browser preview without sending.

Gotchas and Tips

• Laravel version drift. Last release was Feb 2021 and the package targets Laravel 5.x mailables. On Laravel 8+, Mailable changed slightly (envelope/render() conventions in newer versions). Before installing on a current project, check composer.json's illuminate/* constraint – the safest approach is to copy the base class into app/Mail/BaseTuxedo.php and drop the dependency rather than fight the version pin.

• subject() vs $subject vs envelope(). Tuxedo's convention (methods like subject() and template()/view()) predates Laravel 9's envelope() rewrite. If you migrate to Laravel 9+ and keep the package, override envelope() in a subclass rather than relying on the older magic. Otherwise the subject may be silently ignored.

• View not found errors are the #1 failure mode. If template() returns a view path that isn't registered, Mail::send throws at render time, not at construction. Render your mailable in a test ((new WelcomeEmail($user))->render()) to catch this in CI.

• with() only merges into the view – it doesn't populate public properties. If your test asserts $mail->user, you must set $this->user in the constructor, not pass it via with(). Mixing the two styles is a common source of "the mailable is empty" bugs.

• Facade alias registration in package auto-discovery. If you're on Laravel 5.4 or earlier, the facade Tuxedo is not auto-aliased. Add 'Tuxedo' => TomIrons\Tuxedo\Facades\Tuxedo::class to config/app.php or the fluent calls will throw class not found.

• Attachments and build() order. If you add attachments or customize headers, do it in build() (or the constructor) before the parent build() runs. Tuxedo's base class delegates to Mailable::build(), so any ->attach() calls after send() are no-ops.

• Extension point: the base class is small enough to extend further. The cleanest pattern is a project-local abstract App\Mail\TransactionalEmail extends Tuxedo that sets your default layout, from address, and reply-to – then all concrete emails extend that, and you have a single place to bump branding or sender policy.

• Debugging tips: if a send silently succeeds but no email arrives, log Mail::getSwiftMailer()->getTransport() (Laravel ≤8) or inspect the MessageSent / MessageSending events. Tuxedo doesn't intercept these, so standard Laravel mail debugging applies – but confirm the events fire, because a misconfigured template() can produce a zero-byte message that some transports drop without erroring.