Mimemap Laravel Package

Product Decisions This Supports

• Build vs. buy on file-handling plumbing. Every product that accepts uploads eventually needs two-way MIME ↔ extension mapping (.docx → application/vnd.openxmlformats-officedocument.wordprocessingml.document, and back). It looks like a 20-line lookup table and is not: IANA registers ~1,600 media types, hundreds share extensions, extensions are case-insensitive, and Content-Type fields carry parameters (; charset=utf-8) that break naive string comparisons. This package is a buy decision that removes a recurring bug class for near-zero cost.
• Feature scoping for upload/download surfaces. Concrete roadmap items this unblocks or de-risks: correct Content-Disposition filenames on download (extension derived from the stored MIME type rather than trusting the client), server-side extension normalization on upload, "download as" / format-conversion pickers, attachment handling in outbound email, and media-library filtering by type family.
• Data freshness as a maintenance line item. Mappings drift — new formats appear, vendors register new types. The package's ability to regenerate its map from upstream sources (IANA, Apache/nginx mime.types, freedesktop) means "keep the MIME table current" becomes a scheduled CLI job rather than a manual PR. That is a real, quantifiable reduction in long-term ownership cost.
• Security posture decisions. Extension/MIME validation is the first gate on upload risk. Deciding where that gate lives (this package for the type-label layer; finfo/magic-byte sniffing for actual content inspection) is an architecture decision worth making explicitly rather than by accident.
• Vendor and dependency policy. The license and maintenance profile here feed directly into the third-party dependency register, which is a governance decision, not just an engineering one.

When to Consider This Package

Adopt when:

• The product accepts arbitrary or semi-arbitrary user uploads and must produce correct, standards-compliant Content-Type and filename responses.
• You need bidirectional mapping at scale, including the long tail of office, archive, audio/video, and CAD formats that hand-maintained arrays always get wrong.
• You want the mapping refreshable from an authoritative source on a schedule instead of curated by hand.
• The team would otherwise spend a sprint building and then perpetually maintaining a mapping table that is not a differentiator.

Look elsewhere when:

• You only ever handle a handful of known types (PDF, JPEG, PNG). Symfony's Mime component ships with Laravel and covers common cases — adding a dependency here is unjustified overhead.
• You need content-based verification (does this file actually contain what its extension claims?). This package maps labels, not bytes; pair it with finfo/fileinfo or a scanning service, and be explicit with stakeholders that it is not a malware or spoofing defense on its own.
• Legal cannot accept LGPL-3.0. For interpreted PHP this is normally a non-issue (no static linking), but enterprises with blanket copyleft bans will escalate it. Confirm early, not at code review.
• You need a vendor with a support contract or SLA. A 26-star, effectively single-maintainer package offers none.

Risk notes to weigh: low adoption means limited community scrutiny; repository metadata is unverified, which is a supply-chain concern worth a manual audit before pinning; and pin an exact version with a committed lockfile — do not float on ^.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost component that fixes a category of customer-visible defects — files that download with the wrong type, attachments that open incorrectly, uploads rejected for the wrong reason. It replaces hand-maintained lookup tables that silently rot with a mapping that can be refreshed from authoritative registries. The investment is measured in hours, the ongoing cost is a scheduled job, and the failure it prevents shows up in support tickets and trust. The one decision requiring their input is license policy.

To engineering: Don't hand-roll MIME mapping — the long tail and Content-Type parameter parsing will eat the sprint and keep eating it. This library gives bidirectional lookup plus regeneration from IANA/Apache/freedesktop sources. Wrap it behind a single internal interface (MimeResolver) so the dependency is swappable and testable, and pair it with finfo for actual content sniffing — this handles the label, not the bytes. Pin the version, vendor the lockfile, and treat the LGPL-3.0 license as a checkbox to clear with legal before we build on it.