Mime Laravel Package

Getting Started

Minimal Steps

1. Installation (updated for v8.1.0-BETA3):

   composer require symfony/mime:^8.1.0-BETA3
   

   Laravel users can pair with symfony/mailer for transport or use Laravel's Mail facade.

2. First Use Case (updated for security fix):

   use Symfony\Component\Mime\Email;
   
   $email = (new Email())
       ->from('sender@example.com')
       ->to('valid-recipient@example.com') // Line breaks in addresses now rejected
       ->subject('Secure Email')
       ->html('<p>Content with <img src="cid:logo"></p>')
       ->text('Plain text fallback.');
   
   // Inline image (preserve filename as of v8.0.9)
   $logo = new DataPart(file_get_contents('logo.png'));
   $logo->contentId = 'logo';
   $logo->fileName = 'logo.png';
   $email->embed($logo);
   

3. Where to Look First:

   • Security Advisory for CVE-2026-45067.
   • Beta3 Changelog.
   • src/Address.php for email validation logic (now stricter).

Implementation Patterns

Core Workflows

1. Secure Email Address Handling (NEW for v8.1.0-BETA3)

Pattern: Validate addresses to prevent injection:

try {
    $email = (new Email())
        ->from('safe@example.com')
        ->to('user@example.com'); // Throws if line breaks exist
    $email->subject('Secure Subject');
} catch (\InvalidArgumentException $e) {
    logger()->warning('Invalid email address: '.$e->getMessage());
}

2. Transactional Emails with Security (updated)

$email = (new Email())
    ->from('noreply@example.com')
    ->to('user@example.com') // Validated automatically
    ->subject('Order Confirmation #'.$order->id)
    ->html(view('emails.order', ['order' => $order]));

// Inline image with preserved filename
$logo = new DataPart(file_get_contents(public_path('logo.png')));
$logo->contentId = 'order_logo';
$logo->fileName = 'logo.png';
$email->embed($logo);

// Send via Laravel Mail facade
Mail::to('user@example.com')->send($email);

3. Multipart Emails with Validation (updated)

$html = new TextPart($htmlContent);
$html->contentType = 'text/html';

$text = new TextPart($textContent);
$text->contentType = 'text/plain';

$email = (new Email())
    ->from('newsletter@example.com')
    ->to('valid@example.com') // Auto-validated
    ->subject('Weekly Newsletter')
    ->addPart($html)
    ->addPart($text);

4. Laravel Integration with Security (updated)

class SecureMailable extends Mailable
{
    public function build()
    {
        $email = (new Email())
            ->from('app@example.com')
            ->to($this->user->email); // Validated by Symfony MIME

        // Add inline image
        $logo = new DataPart(file_get_contents(public_path('logo.png')));
        $logo->contentId = 'logo';
        $logo->fileName = 'logo.png';
        $email->embed($logo);

        return $this->withSwiftMessage(function ($message) use ($email) {
            $message->setFrom($email->getFrom());
            $message->setTo($email->getTo());
            $message->setSubject($email->getSubject());
            $message->setBody($email->getHtmlBody());
        });
    }
}

Gotchas and Tips

Pitfalls (updated)

1. Email Address Injection (NEW for v8.1.0-BETA3):

   • Issue: to()/from() now reject addresses with line breaks (CVE-2026-45067).
   • Fix: Sanitize addresses before passing:

     $cleanEmail = str_replace("\n", '', $userInputEmail);
     $email->to($cleanEmail);
     

2. Inline Part Filename Overwrite (still fixed in v8.1.0-BETA3):

   • Fix: Explicitly set fileName:

     $image->fileName = 'original-name.png'; // Respected in v8.0.9+
     

3. Beta3 Breaking Changes (NEW):

   • Issue: Address constructor now validates strictly.
   • Fix: Use new Address('valid@example.com') instead of raw strings.

4. MIME Type Guessing (unchanged):

   • Fix: Explicitly set contentType for edge cases.

Debugging Tips (updated)

1. Validate Addresses Early:

   use Symfony\Component\Mime\Address;
   
   try {
       $address = new Address('user@example.com'); // Throws if invalid
   } catch (\InvalidArgumentException $e) {
       // Handle error
   }
   

2. Common Errors:

   • InvalidArgumentException: Line breaks in addresses (new in v8.1.0-BETA3).
   • Empty Email: Check to()/from() validation.

3. Logging Headers:

   foreach ($email->getHeaders() as $header) {
       logger()->debug($header->getName().': '.$header->getValue());
   }
   

Extension Points (updated)

1. Custom Address Validation (NEW for v8.1.0-BETA3): Extend Address logic in a custom class:

   class SecureAddress extends Address
   {
       public function __construct(string $address)
       {
           if (str_contains($address, "\n")) {
               throw new \InvalidArgumentException('Line breaks not allowed.');
           }
           parent::__construct($address);
       }
   }
   

2. Laravel Service Provider (updated): Bind with security checks:

   $this->app->bind(Symfony\Component\Mime\Address::class, function ($email) {
       return new Address($email); // Auto-validates
   });
   

3. Transport Integration (unchanged): Use symfony/mailer for SMTP/APIs with validated addresses.