Updated README.md

robtimus · robtimus · commit 908a1a4615b0 · 2018-10-27T20:53:38.000+02:00
diff --git a/README.md b/README.md
@@ -6,10 +6,10 @@ A library to support (streaming) multiparts.
 
 ### multipart/form-data
 
-To create a multipart/form-data object, create a `MultipartFormData` object, add the form fields, and call `finish()`. There are two methods for adding form fields:
+To create a multipart/form-data object, create a `MultipartFormData` instance, add the form fields, and call `finish()`. There are two methods for adding form fields:
 
-* `addValue($name, $value)` adds a string value with the given name.
-* `addFile($name, $filename, $content, $contentType, $contentLength = -1)` adds a file with the given name. The filename, [content](#multipart-files) and content type are required; the content length is optional, and will be ignored if the content is a string.
+* `addValue($name, $value)` adds a string value with the given name. Both arguments are required.
+* `addFile($name, $filename, $content, $contentType, $contentLength = -1)` adds a file with the given name. The name, filename, [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string.
 
 An example:
 
@@ -31,23 +31,61 @@ PHP servers require multiple values or files to be sent with a name that ends wi
     $multipart->addFile('file[]', 'file.html', '<html>Hello World</html>', 'text/html');
     $multipart->finish();
 
+### multipart/related
+
+To create a multipart/related object, create a `MultipartRelated` instance, add the root part and any inline files, and call `finish()`. There are two methods for adding parts:
+
+* `addPart($content, $contentType, $contentLength = -1, $contentTransferEncoding = '')` adds a part without a content disposition. This should be used for the root part. The [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string; the content transfer encoding is optional, and will be used for the `Content-Transfer-Encoding` header if it is set.
+* `addInlineFile($contentID, $filename, $content, $contentType, $contentLength = -1, $contentTransferEncoding = '')` adds an inline file. The content ID, filename, [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string; the content transfer encoding is optional, and will be used for the `Content-Transfer-Encoding` header if it is set.
+
+An example:
+
+    // the multipart object can take an optional pre-existing boundary
+    $multipart = new MultipartRelated();
+    $multipart->addPart(file_get_contents('body.html'), 'text/html');
+    // the content length is irrelevant because the content is a string
+    $multipart->addInlineFile('logo', 'logo.png', base64_encode(file_get_contents('logo.png')), 'image/png', -1, 'base64');
+    $multipart->finish();
+
+To use this inline file in the HTML body, use `cid:logo` as the source of an image.
+
 ### multipart/alternative
 
-To create a multipart/alternative object, create a `MultipartAlternative` object, add the alternatives, and call `finish()`. There is one method for adding alternatives:
+To create a multipart/alternative object, create a `MultipartAlternative` instance, add the alternatives, and call `finish()`. There are two methods for adding alternatives:
+
+* `addMultipart(Multipart $multipart)` adds another multipart as alternative. This is most often used with a multipart/related object.
+* `addPart($content, $contentType, $contentLength = -1, $contentTransferEncoding = '')` adds a part with the given content. The [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string; the content transfer encoding is optional, and will be used for the `Content-Transfer-Encoding` header if it is set.
+
+An example:
+
+    // the multipart object can take an optional pre-existing boundary
+    $multipart = new MultipartAlternative();
+    // $related is a MultipartRelated instance as created above
+    $multipart->addPart(file_get_contents('body.txt'), 'text/plain');
+    $multipart->addMultipart($related);
+    $multipart->finish();
+
+### multipart/mixed
+
+To create a multipart/mixed object, create a `MultipartMixed` instance, add the parts, and call `finish()`. There are three methods for adding parts:
 
-* `addAlternative($content, $contentType, $contentLength = -1, $contentTransferEncoding = '')`. The [content](#multipart-files) and content type are required; the content length is optional, and will be ignored if the content is a string. The optional content transfer encoding will be used for the `Content-Transfer-Encoding` header.
+* `addMultipart(Multipart $multipart)` adds another multipart. This is most often used with a multipart/alternative or multipart/related object.
+* `addPart($content, $contentType, $contentLength = -1, $contentTransferEncoding = '')` adds a part with the given content. This can be used for the bodies of plain text emails. The [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string; the content transfer encoding is optional, and will be used for the `Content-Transfer-Encoding` header if it is set.
+* `addAttachment($filename, $content, $contentType, $contentLength = -1, $contentTransferEncoding = '')` adds a part with content disposition `attachment`. The filename, [content](#multipart-content) and content type are required; the content length is optional, and will be ignored if the content is a string; the content transfer encoding is optional, and will be used for the `Content-Transfer-Encoding` header if it is set.
 
 An example:
 
     // the multipart object can take an optional pre-existing boundary
     $multipart = new MultipartAlternative();
-    $multipart->addAlternative(file_get_contents('body.txt'), 'text/plain');
-    $multipart->addAlternative(base64_encode(file_get_contents('body.html')), 'text/html', -1, 'base64');
+    // $alternative is a MultipartAlternative instance as created above
+    $multipart->addMultipart($alternative);
+    // the content length is irrelevant because the content is a string
+    $multipart->addFile('file.png', base64_encode(file_get_contents('file.png')), 'image/png', -1, 'base64');
     $multipart->finish();
 
-## Multipart files
+## Multipart content
 
-For multiparts that support files, the content can be given in one of three ways:
+The content of a part or file can be given in one of three ways:
 
 * As a string. The content length will be ignored.
 * As a resource that can be read using `fread`. It is up to the caller to close this resource.
@@ -90,6 +128,6 @@ For instance:
 
 ## Non-streaming support
 
-If streaming is not possible (e.g. because a string is required), you can buffer a multipart object in-memory by calling the `buffer` method. This method takes an optional buffer size, and returns the buffered contents. The content length will be set accordingly. Note that you should do this before calling `read` (or `curl_read`), otherwise the buffered contents may not contain all desired contents (especially if you're using resources or callables).
+If streaming is not possible (e.g. because a string is required, like in the `mail` function), you can buffer a multipart object in-memory by calling the `buffer` method. This method takes an optional buffer size, and returns the buffered contents. The content length will be set accordingly. Note that you should do this before calling `read` (or `curl_read`), otherwise the buffered contents may not contain all desired contents (especially if you're using resources or callables).
 
 `Multipart.__toString()` has been overridden to buffer the multipart object as well, so you can achieve the same by casting a multipart object to `string`. The difference is that `buffer` requires the multipart object to be finished.
