Content Disposition Laravel Package

Product Decisions This Supports

• Download/export feature scoping. Every "Export CSV," "Download invoice," "Save media asset," or "Get report PDF" story has a hidden requirement: the file must arrive with the right name on the user's machine. This package is the decision input for whether that behaviour is specified, tested, and owned — or left to whatever header('Content-Disposition: attachment; filename=...') string a developer improvises.
• Internationalization roadmap. Non-ASCII filenames (Chinese, Arabic, Cyrillic, accented Latin) are where naive implementations break: users get download, file (1).pdf, or mojibake. RFC 6266 / RFC 5987 filename* handling with a quoted ASCII fallback is the specific capability that decides whether you can promise "your export keeps its original name" to non-English markets without a support-ticket tail.
• Security and compliance posture. Filenames are attacker-influenced input in any user-upload or user-named-content product. Correct quoting and CRLF-stripping in a Content-Disposition value is a header-injection control, and it belongs on the secure-coding checklist next to output escaping. A vetted implementation makes that control auditable rather than tribal knowledge.
• Build vs. buy vs. copy. This is a single-class utility, not a subsystem. The honest PM framing: the alternatives are (a) depend on this package, (b) hand-roll ~60 lines and own the RFC edge cases forever, or (c) lean on what Symfony/Laravel already ship. Because the license is MIT and the surface area is tiny, "vendor the code and own it" is a legitimate third option and should be on the table.
• Consuming third-party APIs. Products that call external services returning attachments (payment receipts, e-signature documents, carrier labels) need to parse Content-Disposition to learn the filename. That is a distinct use case from generating headers and is the main reason to want a parser rather than a formatter.
• Framework-boundary decisions. This library is framework-agnostic — no service provider, no facade, no config. That supports a deliberate architectural choice: keep header semantics in a small, testable value object rather than scattered across controllers, which pays off if the product later exposes the same downloads through a non-Laravel service.

When to Consider This Package

Adopt it, or at minimum adopt its behaviour, when:

• You serve file downloads from PHP/Laravel and users see filenames they or their customers chose — i.e., the name is data, not a constant.
• You have or plan non-English markets, and filename fidelity is a visible quality signal.
• You need to parse Content-Disposition from upstream responses or multipart payloads, not just emit it.
• You want the header logic behind a single seam you can unit-test, swap, or replace later.
• You are comfortable treating it as a vendorable snippet: 7 stars, 0 dependents, a single maintainer, and no release since May 2023 mean no meaningful security-response guarantee. Pin the version, wrap it behind your own interface, and assume you may fork.

Look elsewhere when:

• The need is actually full HTTP message handling — use symfony/http-foundation, Guzzle, or laminas-http; this package does not model requests, responses, or streams.
• The need is multipart/form-data parsing on inbound uploads — that is your framework's request layer, not this.
• The need is streaming, range requests, resumable downloads, or storage abstraction — this library only touches one header's value and does nothing for bytes on the wire.
• Your Laravel version already gives you an adequate answer. response()->download() / streamDownload() plus Symfony's HeaderUtils::makeDisposition() covers the common path; verify whether your actual gap is UTF-8 filename* fallbacks and parsing before adding a dependency with no maintenance signal.
• Your dependency policy forbids low-adoption packages. In that case, harvest the logic under MIT, add your own tests against your target browsers, and move on — the cost is small and the risk becomes yours either way.
• You need guaranteed PHP-version currency for a future runtime upgrade; validate its constraints against your roadmap before it lands in a critical path.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost correctness fix for a customer-visible quality issue — file downloads that arrive with mangled or generic names, most visibly for non-English users. It carries no infrastructure cost and no vendor contract, and integration is measured in hours. The trade-off to acknowledge plainly: it is a micro-utility with negligible adoption and no recent releases, so we treat it as a component we may own rather than a strategic dependency. Low risk, low cost, modest but real upside in support-ticket reduction and international polish.

To engineering: One job — build and parse Content-Disposition values correctly, including RFC 5987 filename* with an ASCII fallback and safe quoting against header injection. No Laravel wiring, no config, no runtime overhead. Proposed use: wrap it behind a narrow interface in our own code so the dependency is one file to replace, pin the version, add characterization tests for the browsers and languages we actually support, and keep the MIT-licensed source in mind as a fallback if maintenance stalls. Do not extend it into request/response or upload handling — that is out of scope for this library and stays with the framework.