cardinalby / content-disposition
Installs: 121 065
Dependents: 3
Suggesters: 0
Security: 0
Stars: 7
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: >=5.6
Requires (Dev)
- phpunit/phpunit: ^10.0.19
This package is auto-updated.
Last update: 2024-10-24 01:33:00 UTC
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 beattachment
,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