vendor/zendframework/zend-mail/doc/book/message/attachments.md

   1 # Adding Attachments
   2
   3 zend-mail does not directly provide the ability to create and use mail
   4 attachments. However, it allows using `Zend\Mime\Message` instances, from the
   5 [zend-mime](https://github.com/zendframework/zend-mime) component, for message
   6 bodies, allowing you to create multipart emails.
   7
   8 ## Basic multipart content
   9
  10 The following example creates an email with two parts, HTML content and an
  11 image.
  12
  13 ```php
  14 use Zend\Mail\Message;
  15 use Zend\Mime\Message as MimeMessage;
  16 use Zend\Mime\Mime;
  17 use Zend\Mime\Part as MimePart;
  18
  19 $html = new MimePart($htmlMarkup);
  20 $html->type = Mime::TYPE_HTML;
  21 $html->charset = 'utf-8';
  22 $html->encoding = Mime::ENCODING_QUOTEDPRINTABLE;
  23
  24 $image = new MimePart(fopen($pathToImage, 'r'));
  25 $image->type = 'image/jpeg';
  26 $image->filename = 'image-file-name.jpg';
  27 $image->disposition = Mime::DISPOSITION_ATTACHMENT;
  28 $image->encoding = Mime::ENCODING_BASE64;
  29
  30 $body = new MimeMessage();
  31 $body->setParts([$html, $image]);
  32
  33 $message = new Message();
  34 $message->setBody($body);
  35
  36 $contentTypeHeader = $message->getHeaders()->get('Content-Type');
  37 $contentTypeHeader->setType('multipart/related');
  38 ```
  39
  40 Note that the above code requires us to manually specify the message content
  41 type; zend-mime does not automatically select the multipart type for us, nor
  42 does zend-mail populate it by default.
  43
  44 ## multipart/alternative content
  45
  46 One of the most common email types sent by web applications is
  47 `multipart/alternative` messages with both text and HTML parts.
  48
  49 ```php
  50 use Zend\Mail\Message;
  51 use Zend\Mime\Message as MimeMessage;
  52 use Zend\Mime\Mime;
  53 use Zend\Mime\Part as MimePart;
  54
  55 $text = new MimePart($textContent);
  56 $text->type = Mime::TYPE_TEXT;
  57 $text->charset = 'utf-8';
  58 $text->encoding = Mime::ENCODING_QUOTEDPRINTABLE;
  59
  60 $html = new MimePart($htmlMarkup);
  61 $html->type = Mime::TYPE_HTML;
  62 $html->charset = 'utf-8';
  63 $html->encoding = Mime::ENCODING_QUOTEDPRINTABLE;
  64
  65 $body = new MimeMessage();
  66 $body->setParts([$text, $html]);
  67
  68 $message = new Message();
  69 $message->setBody($body);
  70
  71 $contentTypeHeader = $message->getHeaders()->get('Content-Type');
  72 $contentTypeHeader->setType('multipart/alternative');
  73 ```
  74
  75 The only differences from the first example are:
  76
  77 - We have text and HTML parts instead of an HTML and image part.
  78 - The `Content-Type` header is now `multipart/alternative`.
  79
  80 ## multipart/alternative emails with attachments
  81
  82 Another common task is creating `multipart/alternative` emails where the HTML
  83 content refers to assets attachments (images, CSS, etc.).
  84
  85 To accomplish this, we need to:
  86
  87 - Create a `Zend\Mime\Part` instance containing our `multipart/alternative`
  88   message.
  89 - Add that part to a `Zend\Mime\Message`.
  90 - Add additional `Zend\Mime\Part` instances to the MIME message.
  91 - Attach the MIME message as the `Zend\Mail\Message` content body.
  92 - Mark the message as `multipart/related` content.
  93
  94 The following example creates a MIME message with three parts: text and HTML
  95 alternative versions of an email, and an image attachment.
  96
  97 ```php
  98 use Zend\Mail\Message;
  99 use Zend\Mime\Message as MimeMessage;
 100 use Zend\Mime\Mime;
 101 use Zend\Mime\Part as MimePart;
 102
 103 $body = new MimeMessage();
 104
 105 $text           = new MimePart($textContent);
 106 $text->type     = Mime::TYPE_TEXT;
 107 $text->charset  = 'utf-8';
 108 $text->encoding = Mime::ENCODING_QUOTEDPRINTABLE;
 109
 110 $html           = new MimePart($htmlMarkup);
 111 $html->type     = Mime::TYPE_HTML;
 112 $html->charset  = 'utf-8';
 113 $html->encoding = Mime::ENCODING_QUOTEDPRINTABLE;
 114
 115 $content = new MimeMessage();
 116 // This order is important for email clients to properly display the correct version of the content
 117 $content->setParts([$text, $html]);
 118
 119 $contentPart = new MimePart($content->generateMessage());
 120
 121 $image              = new MimePart(fopen($pathToImage, 'r'));
 122 $image->type        = 'image/jpeg';
 123 $image->filename    = 'image-file-name.jpg';
 124 $image->disposition = Mime::DISPOSITION_ATTACHMENT;
 125 $image->encoding    = Mime::ENCODING_BASE64;
 126
 127 $body = new MimeMessage();
 128 $body->setParts([$contentPart, $image]);
 129
 130 $message = new Message();
 131 $message->setBody($body);
 132
 133 $contentTypeHeader = $message->getHeaders()->get('Content-Type');
 134 $contentTypeHeader->setType('multipart/related');
 135 ```
 136
 137 ## Setting custom MIME boundaries
 138
 139 In a multipart message, a MIME boundary for separating the different parts of
 140 the message is normally generated at random. In some cases, however, you might
 141 want to specify the MIME boundary that is used. This can be done by injecting a
 142 new `Zend\Mime\Mime` instance into the MIME message.
 143
 144 ```php
 145 use Zend\Mime\Mime;
 146
 147 $mimeMessage->setMime(new Mime($customBoundary));
 148 ```