Media Type Laravel Package

Product Decisions This Supports

• API content negotiation (feature). Deciding whether our service can honor an Accept header — including wildcards (text/*, */*), suffixes (application/problem+json, application/hal+json), and quality-ordered variants — versus returning 406 Not Acceptable. This is the single highest-value use case: it is user-visible behavior that is easy to get subtly wrong.
• Upload and media ingestion validation (feature). Whitelisting allowed types on avatar/document/asset uploads, normalizing aliases (image/jpg → image/jpeg), and safely separating a type from its parameters (charset, boundary) before storage or downstream processing.
• Build vs. buy (this is a "buy/adopt," not a "build"). The alternative is a homegrown regex or explode(';') check. That is 20 lines we would own forever, and it is almost always wrong on parameters, quoting, or case-insensitivity. A small MIT value object is cheaper than the review cycles a hand-rolled validator attracts.
• Domain modeling decision (architecture/roadmap). Whether MediaType enters our domain as a typed value object versus a string passed through five layers. Adopting it makes invalid media types unrepresentable at the boundary, which reduces defensive validation further down.
• Roadmap enablers. Signed-URL content-type constraints, webhook payload typing, Vary: Accept-driven cache key derivation, and validating OpenAPI content maps in contract tests all become trivial once a parsed representation exists.
• Decisions it does not inform. Binary storage format, image transcoding/thumbnailing, virus scanning, and MIME sniffing of actual bytes. Do not let the word "media" pull these into scope.

When to Consider This Package

Adopt it when:

• You accept or emit Content-Type / Accept values and currently validate them with regex, str_contains, or naive explode(';') splitting.
• You need correct handling of parameters, wildcards, suffixes, case-insensitivity, and quoted-string parameter values — the parts a regex reliably gets wrong.
• You want a value object that raises on construction rather than a validator you must remember to call. Fail-fast at the HTTP boundary is materially better than a bool you can forget to check.
• You are comfortable reading a small dependency's source before adopting, and willing to pin a version.

Look elsewhere when:

• You need full HTTP message parsing. This models media types, not headers, requests, or negotiation across a full priority list. Use your HTTP layer for that.
• You are on Laravel and only need the common path. Request::accepts(), getAcceptableContentTypes(), and getMimeType() already cover routine negotiation. Buying a package to duplicate framework behavior is not a win.
• You need MIME-to-extension mapping, sniffing, or encoding detection. Reach for symfony/mime or fileinfo instead.
• Bus factor is a hard blocker. Zero stars, zero dependents, and a single-maintainer ecosystem are real signals. If your adoption policy requires community breadth, this fails that gate regardless of code quality — put it behind an internal adapter and treat it as vendorable.
• Your PHP version matrix is behind what the package requires, or you are unwilling to pull in its ecosystem dependencies (Innmind packages lean on immutable collections).

Net: a good fit for a narrowly scoped, well-tested boundary component. A poor fit as a mandated org-wide standard.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed PHP component that turns "is this a valid media type?" into one tested call instead of our own regex. It removes a recurring class of bugs in two places customers actually notice — API content negotiation and upload validation — at effectively zero cost and with no vendor lock-in. We can replace it in an afternoon if we ever want to. Recommendation: pilot in one service, measure, then decide.

For engineering: A typed value object for RFC-style media type strings — parsing, parameter extraction, wildcard and suffix handling, and normalization. It replaces bespoke string handling and gives us a construct that cannot hold an invalid value. Two caveats to price in: adoption signal is essentially nil (0 stars, 0 dependents, single-maintainer ecosystem), so read the source, pin the version, and check its PHP and transitive dependency requirements against our matrix before committing. Wrap it behind a thin internal interface so the swap cost stays trivial. Proposed next step: adopt behind an adapter in the API gateway service, cover the negotiation paths with our own tests, and revisit org-wide use after one quarter of production signal.