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):

.. code-block:: php

   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**

   .. code-block:: php

      use Lacebox\Sole\Mailer;

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

2. **Fluent “to()” syntax**

   .. code-block:: php

      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:

.. code-block:: php

   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
------------------

.. code-block:: php

   <?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.

|
|