Mailer

Sending email is a common need; welcome messages, password resets, notifications. LacePHP’s Mailer wraps different delivery methods (PHP mail(), SMTP, Mailgun) behind a single, simple API.

Why a Mailer Matters

• Consistency One interface for all transports: PHP’s mail(), SMTP servers or third-party APIs.

• Configurability Switch drivers in config(‘mail’) without changing your code.

• Reusability Chainable “fluent” calls keep your controllers clean and readable.

Configuration

Define mail settings in config/mail.php (or your environment):

return [
    'driver' => env('MAIL_DRIVER', 'php_mail'),
    'from'   => ['address'=>'noreply@example.com','name'=>'MyApp'],
    'smtp'   => [
        'host'       => env('SMTP_HOST', 'smtp.example.com'),
        'port'       => env('SMTP_PORT', 587),
        'username'   => env('SMTP_USER', ''),
        'password'   => env('SMTP_PASS', ''),
        'encryption' => env('SMTP_ENCRYPTION', 'tls'),
    ],
    'mailgun'=> [
        'domain'   => env('MG_DOMAIN', ''),
        'api_key'  => env('MG_API_KEY', ''),
        'endpoint' => env('MG_ENDPOINT', 'https://api.mailgun.net/v3'),
    ],
];

The driver key chooses between:

• php_mail → PHP’s native mail()

• smtp → direct SMTP via sockets

• mailgun → Mailgun HTTP API

Basic Usage

1. Direct send

   use Lacebox\Sole\Mailer;
   
   $mailer = new Mailer();
   $success = $mailer->send(
       'user@example.com',
       'Welcome!',
       '<p>Thank you for joining.</p>'
   );
   

2. Fluent “to()” syntax

   use Lacebox\Sole\Mailer;
   
   Mailer::to('user@example.com')
       ->subject('Verify your email')
       ->view('emails.verify', ['token'=>$token])
       ->send();
   

   This will: - Render weave/Views/emails/verify.php with your data - Use the configured driver to deliver the message

Attachments & Headers

Add custom headers or attachments:

Mailer::to('user@example.com')
    ->subject('Invoice')
    ->html($htmlInvoice)
    ->send(
        null,
        [],                     # no custom headers
        ['invoice.pdf' => '/tmp/invoice_123.pdf']
    );

Under the Hood

• PhpMailDriver uses mail() with From: and Content-Type: headers.

• SmtpDriver talks SMTP directly over sockets (EHLO, AUTH, DATA).

• MailgunDriver sends a cURL request to the Mailgun API.

Controller Example

<?php
namespace Weave\Controllers;

use Lacebox\Sole\Mailer;
use function view;

class NotificationController
{
    public function welcome($email)
    {
        if (! filter_var($email, FILTER_VALIDATE_EMAIL)) {
            return kickback()->json(['error'=>'Invalid email'], 422);
        }

        // Prepare HTML with a view
        $html = view('emails.welcome', ['name'=> 'Alice']);

        // Send and check
        $ok = Mailer::to($email)
            ->subject('Welcome to LacePHP')
            ->html($html)
            ->send();

        return kickback()->json(['sent'=>$ok]);
    }
}

Best Practices

• Validate email addresses before sending.

• Use views for consistent templates (headers, footers, CSS).

• Handle failures: check the return value of send() and log errors.

• Queue lengthy sends (e.g. bulk mailing) to avoid blocking web requests.

Warning

• mail() driver cannot send attachments—use SMTP or Mailgun for that.

• SMTP driver requires correct firewall and DNS settings for delivery.

• Mailgun API may impose rate limits or require DNS verification.

• Protect your API keys and SMTP credentials—keep them in .env, not in code.

With LacePHP’s Mailer you can send emails reliably without pulling in a large third-party library—just configure and call.