cardinalby/content-disposition

1.1.1 2023-05-23 22:16 UTC

Requires

• php: >=5.6

Requires (Dev)

• phpunit/phpunit: ^10.0.19

MIT

• Cardinal

README

PHP class for handling (parsing and formatting) a value of HTTP Content-Disposition header.

Requires PHP 5.6 or newer.

Installation

composer require cardinalby/content-disposition 

Content-Disposition header

The text value of the header is in ISO-8859-1 charset. The header contains:

• Type. Can be attachment, inline or custom.
• filename parameter that contains ISO-8859-1 compatible file name.
• filename* parameter that contains a file name in a custom charset (with charset specified and URL-encoded)

API

use cardinalby\ContentDisposition\ContentDisposition;

🔻 static create(...)

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

🔸 $fileName

File name, can contain Unicode symbols. Depending on the symbols present in the string, value will be placed to filename or filename* param.

Pass null to omit filename param.

🔸 $fallback

If the $filename argument is outside ISO-8859-1, then the file name is actually stored in a supplemental filename* field for clients that support Unicode file names and a ISO-8859-1 version of the file name is automatically generated.

This specifies the ISO-8859-1 file name to override the automatic generation or disables the generation at all.

• true (default) will enable automatic generation if the file name is outside ISO-8859-1. Replaces non-ISO-8859-1 characters with '?' character.
• A string will specify the ISO-8859-1 file name to use in place of automatic generation. If it differs from $filename, then $filename option is encoded in the extended field and $fallback set as the fallback field, even though they are both ISO-8859-1
• false will disable including a ISO-8859-1 file name and only include the Unicode version (unless the file name is already ISO-8859-1).
• null will strictly disable including a ISO-8859-1 file name and only include the Unicode version even if file name is already ISO-8859-1.

🔸 $type

Specifies the disposition type, defaults to "attachment". This can also be "inline", or any other value (all values except inline are treated like attachment, but can convey additional information if both parties agree to it). The type is normalized to lower-case.

🔻 static createAttachment(...)

A shortcut for ContentDisposition::create($filename, $fallback, 'attachment');

🔻 static createInline(...)

A shortcut for ContentDisposition::create($filename, $fallback, 'inline');

🔻 format()

Generates the header string value (without header name).

$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()

Generates the full header line: Content-Disposition: ..., where ... equals format() result.

🔻 static parse()

Parses a Content-Disposition header string and returns ContentDisposition object.

$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()

Returns the download type

🔻 getFilename()

Returns a value of filename* param or (if doesn't exist) a value of filename param or null (if none exists).

🔻 getParameters()

Get associative array of all parameters including filename and filename*.

🔻 getCustomParameters()

Get associative array of unknown parameters (except filename and filename*).

References

Reference implementation: content-disposition library for NodeJS.

• RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
• RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters
• RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)
• Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987

License

MIT