包简介

A library to support creating (streaming) multiparts

README 文档

README

A library to support creating (streaming) multiparts.

Supported multipart types

multipart/form-data

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, $contentType = '', $contentTransferEncoding = '') adds a string value with the given name.
- $name and $value are required.
- $contentType is optional, and will be used for the Content-Type header if it is set. It should be set if the implicit content type should not be text/plain.
- contentTransferEncoding is optional, and will be used for the Content-Transfer-Encoding header if it is set.
addFile($name, $filename, $content, $contentType, $contentLength = -1, $contentTransferEncoding = '') adds a file with the given name.
- $name, $filename, $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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 MultipartFormData();
$multipart->addValue('name', 'Rob');
$multipart->addFile('file', 'file.txt', 'Hello World', 'text/plain');
// add a content type to a non-file part
$multipart->addValue('json', '{"id": 1}', contentType: 'application/json')
$multipart->finish();

Multiple values or files with the same parameter name

MultipartFormData follows RFC 7578, and not RFC 2388. This means that multiple values or files with the same parameter name are not sent with a multipart/mixed field but instead as separate parts.

PHP servers require multiple values or files to be sent with a name that ends with []. Because MultipartFormData is written to support also other server types that do not have this requirement, it is up to the caller to add these. For instance:

$multipart = new MultipartFormData();
$multipart->addValue('name', 'Rob');
$multipart->addFile('file[]', 'file.txt', 'Hello World', 'text/plain');
$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.
- $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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.
- $contentID, $filename, $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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
// the content transfer encoding needs to be set to base64
$multipart->addInlineFile('logo', 'logo.png', base64_encode(file_get_contents('logo.png')), 'image/png', contentTransferEncoding: '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 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.
- $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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:

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.
- $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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.
- $filename, $content and $contentType are required.
- $contentLength is optional, and will be ignored if the content is a string.
- contentTransferEncoding 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 MultipartMixed();
// $alternative is a MultipartAlternative instance as created above
$multipart->addMultipart($alternative);
// the content length is irrelevant because the content is a string
// the content transfer encoding needs to be set to base64
$multipart->addFile('file.png', base64_encode(file_get_contents('file.png')), 'image/png', contentTransferEncoding: 'base64');
$multipart->finish();

Multipart content

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.
As a callable that takes a length, and returns a string that is not larger than the given length. If there is nothing more to read it should return the empty string.

Examples, using a MultipartFormData object:

// content length is not necessary
$multipart->addFile('file1', 'file.txt', 'Hello World', 'text/plain');

// make sure to close the resource after the request has been sent
$resource = fopen('file.html');
$multipart->addFile('file.html', $resource, 'text/html', filesize('file.html'));

// assume that class MyResource exists and has a function read($length)
$myResource = new MyResource(...);
$multipart->addFile('file.bin', array($myResource, 'read'), 'application/octet-stream');

cURL support

To send a multipart object with a cURL request, you need to follow some steps:

Set the request type using CURLOPT_CUSTOMREQUEST.
Set the CURLOPT_UPLOAD option to true.
Set the object's curlRead method as the CURLOPT_READFUNCTION.
Make sure the Content-Type and Content-Length headers are set. Note that the Content-Length header is optional.

For instance:

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_UPLOAD, true);
curl_setopt($ch, CURLOPT_READFUNCTION, array($multipart, 'curlRead'));

$headers = ['Content-Type: ' . $multipart->getContentType()];
$contentLength = $multipart->getContentLength();
if ($contentLength >= 0) {
    $headers[] = 'Content-Length: ' .  $contentLength;
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

Non-streaming support

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 curlRead), 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.

robtimus/multipart 适用场景与选型建议

robtimus/multipart 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 1.06M 次下载、GitHub Stars 达 14，最近一次更新时间为 2018 年 10 月 27 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「streaming」「multipart」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 robtimus/multipart 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 robtimus/multipart 我们能提供哪些服务？

定制开发 / 二次开发

基于 robtimus/multipart 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 robtimus/multipart 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

boesing/http-factory-multipart 1

Multipart PSR-7 stream factories based on PSR-17 factories.

hkreuter/graphql-upload 0

A middleware to support file uploads in GraphQL. Forked from ecodev/graphql-upload.

farzai/transport 0

A modern, PSR-compliant HTTP client for PHP with middleware architecture, advanced retry strategies, and fluent API for building requests

jlorente/opentok-laravel 0

A laravel bundle for the OpenTok PHP SDK

sormagec/opentok-laravel 2

Laravel Wrapper for the OpenTok PHP SDK

zappzerapp/laravel-ingest 103

A robust, configuration-driven ETL and data import framework for Laravel. Handles CSV/Excel streaming, queues, validation, and relationships.

robtimus/multipart

包简介

关键字：

README 文档

README

Supported multipart types

multipart/form-data

Multiple values or files with the same parameter name

multipart/related

multipart/alternative

multipart/mixed

Multipart content

cURL support

Non-streaming support

robtimus/multipart 适用场景与选型建议

与 robtimus/multipart 相关的其它包

统计信息

GitHub 信息

其他信息