README

PHP类，用于处理HTTP Content-Disposition头部的值（解析和格式化）。

需要 PHP 5.6 或更高版本。

安装

composer require cardinalby/content-disposition 

Content-Disposition头

头的文本值使用ISO-8859-1字符集。该头包含

• 类型。可以是attachment、inline或自定义。
• 包含与ISO-8859-1兼容的文件名的filename参数。
• 包含在自定义字符集中文件名（包括指定的字符集和URL编码）的filename*参数

API

use cardinalby\ContentDisposition\ContentDisposition;

🔻 静态 create(...)

public static function create(
    $fileName = null, 
    $fallback = true, 
    $type = 'attachment'
)

🔸 $fileName

文件名，可以包含Unicode符号。根据字符串中存在的符号，值将被放置到filename或filename*参数。

传递null以省略filename参数。

🔸 $fallback

如果$filename参数超出了ISO-8859-1，那么文件名实际上存储在一个补充的filename*字段中，以便支持Unicode文件名的客户端使用，同时自动生成ISO-8859-1版本的文件名。

这指定了要覆盖自动生成的ISO-8859-1文件名或完全禁用生成。

• true（默认值）将启用自动生成，如果文件名超出ISO-8859-1，则替换非ISO-8859-1字符为'?'字符。
• 一个字符串将指定要使用的ISO-8859-1文件名，以代替自动生成。如果它与$filename不同，那么即使它们都是ISO-8859-1，$filename选项也会在扩展字段中编码，并且$fallback设置为回退字段。
• false将禁用包含ISO-8859-1文件名，并仅包含Unicode版本（除非文件名已经是ISO-8859-1）。
• null将严格禁用包含ISO-8859-1文件名，并仅包含Unicode版本，即使文件名已经是ISO-8859-1。

🔸 $type

指定处置类型，默认为"attachment"。这也可以是"inline"，或任何其他值（除了inline之外的所有值都被视为attachment，但如果双方同意，可以传达更多信息）。类型被规范化为小写。

🔻 静态 createAttachment(...)

ContentDisposition::create($filename, $fallback, 'attachment')的快捷方式；

🔻 静态 createInline(...)

ContentDisposition::create($filename, $fallback, 'inline')的快捷方式；

🔻 format()

生成头字符串值（不包含头名称）。

$v = ContentDisposition::create('£ and € rates.pdf')->format();
// 'attachment; filename="£ and ? rates.pdf"; filename*=UTF-8\'\'%C2%A3%20and%20%E2%82%AC%20rates.pdf'

🔻 formatHeaderLine()

生成完整的头行：Content-Disposition: ...，其中...等于format()的结果。

🔻 静态 parse()

解析Content-Disposition头字符串，并返回ContentDisposition对象。

$cd = ContentDisposition::parse('attachment; filename="plans.pdf"');
assert($cd->getType() === 'attachment');
assert($cd->getFilename() === 'plans.pdf');
assert($cd->getParameters() === ['filename' => 'plans.pdf']);

$cd = ContentDisposition::parse(
    'attachment; filename="EURO rates.pdf"; filename*=UTF-8\'\'%E2%82%AC%20rates.pdf'
    );
assert($cd->getType() === 'attachment');
// Unicode version is preferable
assert($cd->getFilename() === '€ rates.pdf');
assert($cd->getParameters() === [
    'filename' => 'EURO rates.pdf', 
    'filename*' => '€ rates.pdf'
]);

🔻 getType()

返回下载类型

🔻 getFilename()

返回filename*参数的值或（如果不存在）返回filename参数的值或null（如果都不存在）。

🔻 getParameters()

获取包含filename和filename*在内的所有参数的关联数组。

🔻 getCustomParameters()

获取除filename和filename*之外的未知参数的关联数组。

参考文献

参考实现：NodeJS的content-disposition库。

• RFC 2616：超文本传输协议 — HTTP/1.1
• RFC 5987：超文本传输协议（HTTP）头字段参数的字符集和语言编码
• RFC 6266：在超文本传输协议（HTTP）中使用Content-Disposition头字段
• HTTP Content-Disposition头字段（RFC 6266）的测试用例以及RFC 2047、RFC 2231和RFC 5987中定义的编码

许可证

MIT