Internet Media Type Interface Laravel Package

Product Decisions This Supports

• Build vs. buy (or rather, build vs. borrow) for content-type handling. This package ships contracts only — InternetMediaTypeInterface and ParameterInterface — not a parser or implementation. The decision it informs is whether to standardise on a third-party set of value-object interfaces for media types, or hand-roll your own DTOs. Because it's interfaces, the cost of adoption is a composer require in a library layer, not an architectural commitment.
• API surface design for internal packages. The 1.0 change from setters to withers is the single most decision-relevant signal here: the maintainer has committed to immutable value objects. If your team is building an HTTP client, a content-negotiation layer, or a webhook dispatcher that passes media types around, this is a reference design worth copying even if you don't adopt the dependency.
• Roadmap: interoperability between first- and third-party PHP components. If you maintain more than one package that touches Content-Type (an API client, an upload handler, a document converter), a shared interface lets those packages compose without a hard dependency between them. That is a real roadmap enabler for a platform/SDK play.
• Feature scoping for content negotiation. Deciding whether media-type parsing is in scope for v1 of a product. This package defines the vocabulary (type, subtype, parameters) but you still own the parser and the matching logic — so it does not reduce scope meaningfully; it only standardises naming.
• Risk posture on 0.x dependencies. The 0.4 → 1.0 jump with two breaking PRs is a data point for any "do we pin dev dependencies to 0.x?" policy discussion.

When to Consider This Package

Adopt when all of the following hold:

• You are publishing a PHP library or SDK (not an application) where other people implement or consume media-type objects, and a shared interface genuinely removes coupling.
• You are already in the webignition ecosystem, or your dependency graph already pulls it in transitively — in which case this release is a required migration, not an optional evaluation.
• You want a small, dependency-free contract layer and are comfortable that you will write (or separately source) the actual parsing, validation, and matching.

Look elsewhere when:

• You are building a Laravel application. There is nothing Laravel-specific here — no service provider, no facade, no config, no Eloquent integration. It is a framework-agnostic PHP interface package. For request/response and MIME handling in a Laravel app, symfony/mime and league/mime-type-detection cover the practical use cases with far more functionality.
• You need behaviour, not contracts. If the question is "how do I parse text/html; charset=utf-8 and match it against an Accept header?", this package does not answer it. Interfaces alone deliver zero runtime capability.
• You need extension-to-MIME mapping (.jpg → image/jpeg) — different problem, use a dedicated detection library.
• You are pre-1.0-sensitive. This package has now demonstrated it will break interfaces across minor versions (0.4 → 1.0 removed ParameterInterface setters outright). Fine for a greenfield library, painful if you have downstream consumers.

How to Pitch It (Stakeholders)

For executives: This is a small, narrow infrastructure dependency — a set of PHP interfaces describing how internet media types (MIME types) are represented. It delivers no user-facing capability on its own. The 1.0 release marks it as stable and makes a deliberate design choice toward immutable objects, which is good engineering hygiene but carries a breaking change for anyone already on 0.x. Recommendation: no action unless we already depend on it transitively, in which case budget a small migration.

For engineering: Version 1.0 is a breaking release. ParameterInterface loses its setters, and InternetMediaTypeInterface replaces setters with with*() withers — meaning implementations must now be immutable and must return new instances rather than mutating in place. If we consume this package anywhere, every implementing class needs rewriting, and any code doing $mediaType->setType(...) will fatal. The immutability contract is a genuine improvement (safe as cache keys, safe under Octane/long-running workers, no defensive copying), so the migration is worth doing properly rather than pinning to 0.4. Note it is interfaces only — we own the parser either way, so this does not reduce our implementation work; it only standardises the shape of the objects we pass between packages.