Laminas Mime Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require oroinc/laminas-mime
   

   Replace laminas/laminas-mime with oroinc/laminas-mime in your composer.json if already installed.

2. First Use Case: Parse a MIME message (e.g., an email) to extract parts like headers, body, and attachments:

   use OroInc\LaminasMime\Message;
   
   $message = Message::fromString($rawEmailString);
   $headers = $message->getHeaders();
   $body = $message->getBody();
   

3. Key Classes to Explore:

   • OroInc\LaminasMime\Message: Core class for parsing MIME messages.
   • OroInc\LaminasMime\Part: Represents individual parts of a MIME message (e.g., attachments).
   • OroInc\LaminasMime\Mime: Utility class for MIME type handling.

4. Documentation: Refer to the original Laminas MIME docs (APIs remain identical). Focus on:

   • Message API
   • Part API

Implementation Patterns

Common Workflows

1. Parsing Emails:

   $message = Message::fromString($emailContent);
   foreach ($message->getParts() as $part) {
       if ($part->isAttachment()) {
           $attachment = $part->getContent();
           // Save or process attachment
       }
   }
   

2. Building MIME Messages:

   $message = new Message();
   $message->setEncoding('8bit');
   $message->setBody('Hello, World!');
   $message->getHeaders()->addHeaderLine('Subject', 'Test Email');
   $messageString = $message->toString();
   

3. Handling Multipart Messages:

   $multipart = new Multipart('mixed');
   $multipart->addPart(new Part('This is part 1'));
   $multipart->addPart(new Part('This is part 2'));
   $message->setBody($multipart);
   

4. Integration with Laravel:

   • Use with illuminate/mail for custom email parsing/manipulation.
   • Example: Parse incoming emails in a queue job:

     use OroInc\LaminasMime\Message;
     use Illuminate\Support\Facades\Mail;
     
     Mail::raw($rawEmail, function ($message) {
         $laminasMessage = Message::fromString($rawEmail);
         // Extract data from $laminasMessage and attach to $message
     });
     

5. MIME Type Handling:

   use OroInc\LaminasMime\Mime;
   
   $mimeType = Mime::typeOf('example.pdf'); // 'application/pdf'
   $extension = Mime::extensionOf('application/json'); // 'json'
   

Integration Tips

• Laravel Mail Drivers: Extend Swift_Transport or Swift_Mailer to inject OroInc\LaminasMime for custom MIME processing.
• File Uploads: Validate MIME types of uploaded files using Mime::typeOf().
• API Responses: Dynamically generate MIME responses (e.g., JSON with attachments):

  return response($laminasMessage->toString())
      ->header('Content-Type', $laminasMessage->getMediaType());
  

Gotchas and Tips

Pitfalls

1. PHP 8.4 Compatibility:

   • The fork fixes PHP 8.4 issues, but test thoroughly. Report edge cases to the fork's issues.
   • Avoid mixing with the original laminas/laminas-mime in the same project.

2. Deprecated Features:

   • Some Laminas MIME methods (e.g., getRawHeaders()) may be deprecated. Use alternatives like getHeaders().
   • Check Laminas RFCs for breaking changes.

3. Performance:

   • Parsing large MIME messages (e.g., emails with many attachments) can be memory-intensive. Stream parts if possible:

     $part->getContentStream(); // If available
     

4. Encoding Issues:

   • Always specify encoding (e.g., setEncoding('8bit') or 'base64' for binary data). Defaults may break attachments.

5. Multipart Boundaries:

   • Manually generated multipart messages require unique boundaries. Use Multipart::generateBoundary():

     $multipart = new Multipart('mixed', Multipart::generateBoundary());
     

Debugging

• Validate MIME Structure: Use online tools (e.g., MIME Tools) to verify parsed messages match expectations.
• Log Raw Input:

  \Log::debug('Raw MIME input', ['content' => $rawEmail]);
  

• Check Headers:

  $headers = $message->getHeaders();
  $headers->toString(); // Log or inspect
  

Configuration Quirks

• No Laravel Config: The package is framework-agnostic. Configure via code (e.g., set default encoding in a service provider):

  $this->app->singleton(OroInc\LaminasMime\Message::class, function () {
      $message = new Message();
      $message->setEncoding('7bit'); // Default encoding
      return $message;
  });
  

Extension Points

1. Custom Parts: Extend OroInc\LaminasMime\Part to add domain-specific logic:

   class CustomPart extends Part {
       public function isInvoice() {
           return $this->getContentType() === 'application/invoice';
       }
   }
   

2. MIME Type Overrides: Override Mime::getMimeTypes() to add custom MIME mappings:

   Mime::getMimeTypes()->offsetSet('custom/type', ['custom']);
   

3. Event Listeners: Attach listeners to Message or Part events (if supported in the fork). Example for original Laminas:

   $message->getEventManager()->attach('part.add', function ($event) {
       // Handle part addition
   });
   

Migration Tips

• From laminas/laminas-mime: Replace namespace imports:

  - use Laminas\Mime\Message;
  + use OroInc\LaminasMime\Message;
  

• From symfony/mime: Key differences:
  • Laminas uses Message::fromString() vs Symfony’s Email::fromString().
  • Part handling is more granular in Laminas (e.g., getParts() vs Symfony’s getAttachments()).

Community Notes

• Active Maintenance: The fork is untested in production. Prefer symfony/mime for new projects.
• Testing: Use PHPUnit with oroinc/laminas-mime in composer.json:

  composer require --dev oroinc/laminas-mime