Craftable Media Laravel Package

Product Decisions This Supports

• Build vs. buy for media. This is fundamentally a "don't build it" decision. Polymorphic file attachments, named collections, thumbnails, and URL generation are commodity capability. Adopting a package turns "media support" from a multi-sprint in-house build with permanent maintenance into roughly a half-day integration on a first model. This package is one candidate; the decision it feeds is whether we buy at all, which we should.
• Two-layer decision, not one. dejwcake/craftable-media is a fork of brackets/media sitting on top of spatie/laravel-medialibrary. So: (1) adopt the commodity base — yes, near-certain; (2) adopt this wrapper — only if we are standardising admin UX on Craftable. If we're not on Craftable, the correct call is the upstream library, and this package drops out of the evaluation entirely.
• Feature unlock and roadmap sequencing. Galleries, document attachments, avatars, and private/paid file delivery become configuration rather than custom code. Because it attaches to an existing Eloquent model via a trait, media can slot into a feature sprint instead of gating a release on schema redesign — it converts a platform item into a feature item.
• Upload policy becomes a product decision, not an engineering one. Collection rules (max files, max size, accepted MIME types, per-collection permissions) are declarative. We can specify and later change upload policy in requirements conversations without rework — worth pricing into scoping.
• Risk budgeting for a sticky dependency. Media is one of the hardest things to swap: once rows exist and objects sit on a disk, changing packages means data migration plus rewriting every URL already served or embedded. That asymmetry justifies a contained pilot before we commit it to any customer-visible surface.
• Platform-version signal. The package targets PHP 8.5 / Laravel 13. That is a forward-looking constraint we should read as an input to the platform upgrade conversation, not as a reason to pick a media package.

When to Consider This Package

Adopt when:

• The host application is on PHP ^8.5 and Laravel 13. This is a hard gate. The package's own conventions require it; on an older stack, treat this as unavailable and revisit after a platform upgrade rather than bending the platform around a media library.
• We are already in — or deliberately committing to — the Craftable admin ecosystem, and want editor-facing upload UX out of the box.
• Editors, not engineers, own the assets. The request-driven add/update/delete flow and thumbnail hooks pay off most when non-technical users manage media day to day.
• Requirements are standard: images and documents, a handful of conversions, local disk or an S3-compatible store, and one queue worker.

Look elsewhere when:

• We're not on Craftable. Use spatie/laravel-medialibrary directly — same underlying capability, vastly larger community, and a documented breaking-change surface we can diff against. This is the likely outcome of most evaluations.
• Requirements are video transcoding, DRM, or DAM-shaped (rights, versioning, taxonomies). This is an attachment layer, not a digital asset manager.
• We need a vendor SLA or a named support owner. Zero stars, single-maintainer concentration, and an unresolved identity question (public upstream vs. internal fork vs. vendor distribution) mean best-effort support only. Anything load-bearing and user-visible needs an internal owner and a documented fallback.
• Compliance or data-residency obligations demand a proven library with a published security-response process.
• We can't be on PHP 8.5 / Laravel 13 within the planning horizon.

How to Pitch It (Stakeholders)

For executives — one paragraph: Media attachments are solved infrastructure, not differentiated product. We can ship galleries, document attachments, and gated file downloads in a feature sprint by adopting a Laravel package instead of building upload, storage, thumbnailing, and cleanup ourselves — roughly half a day of integration for a first model, plus a queue worker for image processing, versus a multi-sprint in-house build we would then own forever. The specific package in front of us, craftable-media, is a thin wrapper in the Craftable admin ecosystem built on the widely used spatie/laravel-medialibrary. That splits the decision cleanly: take the commodity base, and take this wrapper only if we standardise our admin on Craftable. Two caveats stated up front and honestly: it requires PHP 8.5 / Laravel 13, so it is gated on our platform version; and it is a single-maintainer, zero-star package, so we should assume support is ours and keep a fallback. Ask: approve a one-model pilot behind a flag — not a platform commitment. Defer broad rollout until the pilot validates our storage and queue story.

For engineering — the practical read: Integration is composer install, publish and review migrations, attach a trait to one model, configure one disk, verify upload → retrieve → URL end-to-end, then enable one conversion on the queue. No infrastructure prerequisite beyond a storage target and a worker. The recent 2.0.1 release is maintenance-only and upgrade-safe, and the multi-database CI (PostgreSQL and MariaDB) is a genuine positive signal for teams not on MySQL. The risks to manage are environmental rather than version-related: disk permissions and driver credentials (which fail as broken image URLs, not exceptions), conversion failures that leave records pending with no alert, orphaned files accumulating over time, and container resolution outside a fully bootstrapped app. Mitigate all of them with one thing — an end-to-end smoke check in CI that uploads, converts, and fetches against the real storage driver — plus a periodic reconciliation job budgeted early, and a CDN in front of generated URLs so the app isn't in the delivery path.