Mediable Laravel Package

Product Decisions This Supports

Feature: ship a media picker instead of building one. Mediable covers the 80% case for "pick a file and put it in a form field" — upload, browse, select, insert into a target input, plus WebP/AVIF derivatives on upload. If the roadmap has any of these, it is a direct substitute for 2–6 weeks of build:

• Rich-text/blog editor image insertion (the README's own named use case: "injecting content into blog posts")
• Carousel, hero, and gallery slot management
• Product preview / catalog imagery
• Document, audio, and video attachment for support content, courses, or listings
• Any admin screen currently using a raw <input type="file"> plus manual filename hygiene

Roadmap sequencing. This package lets you demote "asset management" from a quarter-sized initiative to a sprint-sized integration, which frees capacity for higher-leverage work. It converts a build decision into a platform-currency decision, because adopting it means being on PHP 8.5, Laravel 13.20, and Livewire 4.x. That is the real choice on the table — not "do we need media."

Build vs. buy vs. integrate. Frame it as three options, not two:

1. Integrate Mediable — lowest cost, highest version-coupling risk (20 stars, 0 dependents, single maintainer, MIT).
2. Integrate a mature library (e.g. Spatie Media Library) + build the picker UI — higher cost, healthier ecosystem, you own the UX.
3. Buy a DAM / cloud media service — ongoing spend, justified only by roles, approvals, taxonomy, and transformations at scale.

Mediable sits firmly at option 1 and should be evaluated against option 2 on total cost, not license cost (both are MIT).

Platform and non-functional decisions it forces, usefully:

• Image format policy — WebP/AVIF generation is on by default with tunable quality (MEDIABLE_WEBP_QUALITY), so you get a defensible Core Web Vitals / bandwidth story without building a transform pipeline.
• Storage strategy — the disk is configuration ('disk' => 's3'), so local-vs-object-storage becomes a config decision rather than a rewrite. Good: it keeps the exit cost low.
• Upload policy — allowable MIME types and max size live in one config file, which is where a security/abuse review should focus. Note the README's own example of adding svg to the allowlist; that needs review, not a copy-paste.

What it does not decide for you. No roles/permissions, no approval workflow, no asset taxonomy or tagging model, no audit trail, no CDN integration. If the roadmap requires any of those, this is a component, not a platform — budget accordingly rather than assuming the media problem is closed.

Governance decision that should accompany adoption: pin the version, vendor or fork it internally, and keep the attachments table behind your own domain abstraction so your product models never depend on its schema directly.

When to Consider This Package

Consider it when all of these hold:

• Your app is already Livewire-based — this is a Livewire component, not a framework-agnostic toolkit; it delivers no value outside that stack.
• You are on (or actively migrating to) PHP 8.5 / Laravel 13 / Livewire 4. This is a hard gate, not a preference — on Laravel 10/11/12 the install will not resolve.
• The requirement is selection and insertion, not asset lifecycle management. The integration surface is genuinely small: one component, two events (mediable.open, mediable.on), one migration, two Blade directives.
• You can own the risk: one maintainer, 20 stars, zero dependents, no commercial support. Treat it as code you are adopting, not a vendor you are buying from.
• Files can live on your own disk and the attachments table is an acceptable storage shape.
• You are willing to run a 1–2 day spike against your actual upload requirements before committing it to a roadmap.

Look elsewhere when any of these hold:

• Version mismatch. Pre-Laravel-13 or pre-PHP-8.5 is an immediate no. Watch the release cadence here: the changelog shows the package chasing new Laravel/PHP majors, which is good for currency and bad for predictability.
• You need a real DAM. Roles, approvals, tagging, collections, usage tracking, or rights management are out of scope and will be rebuilt on top of it at greater cost than starting from a mature library.
• You need transformation pipelines beyond the basics. The GD-based tools (flip, scale, filter, rotate, crop, text) are convenient, but a design-led product usually needs art-directed crops, focal points, and CDN-level delivery.
• Procurement or security requires a supported dependency — an SLA, a security contact, or a maintained advisory feed. Zero dependents also means near-zero external scrutiny; you are the first reviewer of this code.
• Multi-tenant or high-volume asset workloads are core to the product rather than incidental.
• You are on Filament or Nova and a first-party or well-established media manager already fits.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can deliver media insertion — the ability to upload an image or document and drop it into a blog post, carousel, or product listing — in roughly a sprint instead of a quarter, using a free (MIT), self-hosted Laravel component with no per-seat or per-asset fees. It also gives us modern image formats (WebP/AVIF) by default, which helps page speed and bandwidth without a separate project. The trade-off is maturity: it is a small, single-maintainer open-source project with a narrow version window, so we should treat it as code we adopt and can maintain ourselves rather than a vendor product. Because it stores files on our own storage and metadata in one ordinary table, the cost of replacing it later is low. Recommendation: approve a short technical spike, then decide — the downside is bounded and the schedule upside is real.

For engineering (the actual ask):

• What we'd be taking on: a Livewire 4 media-manager component, a config file (allowed MIME types, max size, disk, folder), one attachments migration, two events, and two Blade directives. No service provider gymnastics, no exotic dependencies beyond gd/imagick.
• Why it's cheap to back out: data is files on our disk plus a single table; there is no proprietary format and no external service. Keeping our domain models decoupled from attachments preserves that option.
• What we must verify in the spike, in priority order:
  1. Dependency resolution on our actual PHP/Laravel/Livewire versions — this is the most likely blocker and the cheapest thing to falsify.
  2. Upload validation and abuse surface — the MIME allowlist is our security boundary; decide deliberately on svg and archive types, and confirm server-side validation isn't bypassable by the client.
  3. Storage and delivery — storage:link, APP_URL correctness, and whether the S3 path actually works for us (background conversion cost, signed URLs).
  4. Conversion behavior at our volumes — WebP/AVIF on upload is synchronous work; measure upload latency and queue implications on large images.
  5. Garbage collection for orphaned attachments (added in 1.5.0) — confirm it actually runs and is safe under our data-retention rules.
• Ask: 1–2 engineering days to spike, then a go/no-go. If go: pin the version, vendor the package, and write a short internal note on how we'd fork it if the maintainer walks away. If no-go: fall back to a mature media library plus our own picker UI — same feature, more build, less version risk.