Laravel Mediable Laravel Package

Product Decisions This Supports

• Build vs. buy for media handling. This package replaces the custom "uploads" table, polymorphic pivot, upload service, and image-resize plumbing most Laravel teams write from scratch. The decision it de-risks: do we build a bespoke media layer (2–4 sprint weeks plus ongoing maintenance) or adopt an 828-star, MIT-licensed, actively released package and spend that time on product differentiation?
• Feature scoping for attachment-heavy features. It directly enables roadmap items that are otherwise multi-sprint: product galleries, post thumbnails/featured images, downloadable documents, user avatars, receipt/invoice attachments, CMS asset libraries. If a roadmap item is "let users attach N files of type X to entity Y," this is the shortest credible path.
• Data model architecture. The many-to-many polymorphic relationship means media attaches to any model without modifying that model's schema. This is a reversible architectural decision — it delays the "do we add image_url columns to every table?" fork and keeps the media concern orthogonal to domain tables. Worth approving early because retrofitting it later is a migration project.
• Storage and delivery strategy. The filesystem-driven design plus per-disk configuration lets you defer the local-vs-S3 decision: start on local disk, move to S3 later via moveToDisk()/copyToDisk(), with S3 temporary URL support for private assets. This is a decision-enabler for the "when do we invest in cloud storage / signed URL delivery?" question.
• Accessibility as a first-class requirement. v6 added an alt attribute on Media records with withAltAttribute(). If accessibility (WCAG/ADA) is on the compliance roadmap, this converts "we'll retrofit alt text later" into a schema-level commitment now — a cheap, high-leverage yes.
• Image variant strategy and rendering cost. Built-in intervention/image integration with synchronous or queued variant generation, plus optional optimization via spatie/image-optimizer. This supports the decision on whether thumbnails are generated at upload time (better UX, more storage/CPU) or on demand, and whether image optimization is in scope or deferred.
• Upload validation and abuse posture. MIME type, extension, and aggregate-type restrictions (e.g. image), content-inferred MIME by default (v6 flipped the default away from client-supplied MIME), validateHash() for integrity checking, and filename sanitization/transliteration. These are the controls you need to answer a security review question before launch rather than after an incident.
• Priority call on "media platform" ambitions. Because it is deliberately a library, not a DAM, it clarifies scope boundaries: it justifies a "no" to in-app video transcoding, AI tagging, or a full asset-management UI, and a "yes" to integrating a third-party service if those become real requirements.

When to Consider This Package

Good fit:

• The application is Laravel 10/11 on PHP 8.1+ (v6 dropped Laravel 8/9 and PHP 7.4/8.0) and the team is already fluent in Eloquent.
• You need polymorphic, tag-based attachments across multiple models ("thumbnail", "featured image", "gallery", "download") — the tagging model is the core value proposition and is awkward to replicate cleanly.
• You want image variants (resize/crop) and are willing to adopt intervention/image v3 as a peer dependency.
• You need multiple upload destinations with different accessibility (public CDN assets vs. private user documents) configurable per disk.
• You want private-asset delivery on S3 via temporary URLs without writing signing logic.
• You need an auditable, hash-verified upload path (integrity checks, content-derived MIME, sanitized filenames).

Look elsewhere when:

• The scope is one image per record — a single image_path column and Laravel's native Storage facade is less machinery than a migrations + service provider + polymorphic pivot install.
• Non-Laravel or polyglot stack, or a frontend-heavy app where uploads are handled by a separate service.
• You need transformation-on-the-fly via URL (Cloudinary/imgix-style ?w=300&fit=crop), global CDN edge delivery, or responsive srcset generation at the edge — this package generates variants server-side and stores them.
• You need video/audio transcoding, PDF rendering, OCR, or AI tagging — out of scope by design.
• You need a DAM with an admin UI, approval workflows, asset versioning/lineage, or license/rights metadata — this is a developer library, not an application.
• Enterprise procurement or long-term vendor-risk constraints apply: it is a single-agency-maintained MIT package with a modest star count and no commercial support tier. If your org requires an SLA, look at a hosted media service.
• Strict multi-tenant file isolation is a hard requirement — verify carefully; disk/prefix conventions are yours to enforce, not the package's.
• You cannot accept the upgrade treadmill: v6 was a breaking release (refactored SourceAdapters, removed methods, PHP/Laravel floor bumped). Plan for a major-version upgrade every couple of years.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: For our Laravel application, plank/laravel-mediable is an 828-star, MIT-licensed, actively maintained package that gives us file uploads, attachment-to-any-record, tagged media roles, automatic image resizing, and private cloud-storage delivery out of the box. Adopting it converts several recurring roadmap features — galleries, thumbnails, document attachments, user avatars — from bespoke engineering projects into configuration. Because it is MIT and free, our spend is measured in integration days, not licence fees; and because it is a library rather than a platform, we keep the option to swap in a hosted media service later if we ever need video, CDN transforms, or a full asset-management UI. The main trade-off to accept is that it is community-maintained with no commercial SLA, so we own upgrades — most recently a breaking v6 release that requires PHP 8.1+ and Laravel 10/11.

For engineering — what you're actually signing up for:

• Composer install, service provider (auto-discovered on modern Laravel), published config, and two migrations for a media table plus polymorphic pivot.
• Usage is a three-line upload → attach → retrieve flow, with a MediaUploader supporting local files, remote URLs, streams, and data URLs.
• New hard dependencies in practice: intervention/image v3 for manipulation and optionally spatie/image-optimizer for compression.
• v6 is a genuine breaking change (SourceAdapter rewrite, streamed metadata reads instead of in-memory, removed getContents()/path()/valid(), content-derived MIME by default). Budget migration time if we are on v5.
• We still own: upload endpoints/validation UX, authorization policies, virus scanning, tenant isolation conventions, cleanup on record deletion, and any admin UI.
• Recommendation: adopt for the media-attachment layer; explicitly do not adopt as our media platform. Revisit with a hosted service if video, edge transformations, or a DAM UI enter the roadmap.