Media Library Laravel Package

Product Decisions This Supports

• Feature scoping for media-heavy surfaces. The v1.5.0 MediaUploaded queueable event decouples post-upload work (AI alt-text generation, virus scanning, transcription, CDN warm-up, webhook fan-out) from the request lifecycle. This turns "can we afford to do X on upload?" into a scoping question rather than an architecture debate — you can commit to enrichment features in a roadmap without re-planning the upload path each time.
• Build vs. buy for media handling — now including the client side. The package ships upload entry points (helper, trait, Livewire component, HTTP controller) that all funnel through a single service, plus a persisted optimization pipeline state machine (pending → optimized / failed). v1.6.0 extends that same buy case to the frontend: React and Vue useMediaPicker composables, useMediaLibrary, and a MediaModal with a controllable fetch contract (enabled, autoFetch). The undifferentiated plumbing you would otherwise build and maintain now spans both tiers — picker state, modal lifecycle, fetch deferral, cache-on-reopen — not just upload dispatch and image optimization.
• Roadmap sequencing for an admin/media roadmap. The stable optimization block on MediaResource (with TypeScript types OptimizationStatus and MediaOptimization) is the data contract behind an admin "media health" surface: status badges, bytes-saved reporting, generated-format inventory, and failure triage. It makes a "storage cost / asset quality" initiative plannable in slices — badge first, dashboards second — without backend changes between slices.
• Performance and API-cost budgeting for admin surfaces. v1.6.0's enabled option defers the picker's initial media and recently-used fetches until the picker is actually needed, and MediaModal passes its open state through automatically. That converts "our admin pages fire /api/media requests on every load, even for a closed modal" from a refactor into a prop. It is the enabler for embedding the picker in dashboards, tabs, drawers, and heavy pages without an API-load tax — and it gives you a concrete before/after metric (media requests per page load) for a perf initiative.
• Where admin UI gets built (frontend stack choice). React and Vue composables mean the package no longer implies a Livewire-only frontend. That de-risks a roadmap decision to build the admin console in React or Vue against a Laravel API backend — the media picker is not the thing that forces a rewrite.
• Prioritizing operational tooling. media:backfill-optimization-status is a migration/rollout enabler on day one. Any adoption of this version on an existing library is a one-command data migration rather than a "legacy assets look broken" incident, which lowers the cost and risk of scheduling the upgrade.
• Use-case fit signals. Strong fit: content/CMS products, marketplaces, and internal admin tools where editors upload images and downstream consumers (AI enrichment, search indexing, moderation) need to react to uploads asynchronously — and where the picker lives inside modals or lazily-loaded panels. Weak fit: products with no server-side media pipeline, or where a dedicated DAM/CDN vendor already owns optimization and status reporting.
• Deciding where enrichment logic lives. Because the event fires from every upload entry point, you can standardize a product decision ("all post-upload enrichment is a queued listener") instead of leaving it to each team. That is a durable architectural convention worth writing down in the roadmap docs.
• Telemetry and success metrics. optimization_bytes_saved / optimization_original_size give a directly reportable metric ("storage saved"), and the v1.6.0 fetch-deferral behavior gives a companion "wasted API calls eliminated" figure, which supports a launch narrative and post-launch measurement without instrumenting the pipeline or the client yourself.
• Estimated integration effort for modern React/Vue. The v1.6.0 fixes — useMediaLibrary honouring autoFetch: false under React StrictMode re-runs, and the Vue composable no longer swallowing the first filter change when autoFetch is false — remove the two most likely "we'll have to patch the hooks" line items for teams on React 18+ StrictMode or building custom controlled filter UIs. That materially lowers the effort estimate in a build-vs-buy comparison.

When to Consider This Package

Consider adoption when most of the following hold:

• You are on Laravel and already ship (or plan) media uploads through the framework's conventions — the package assumes Laravel events, Eloquent-backed media rows, Artisan commands, and a Laravel API for the frontend hooks. If your backend is not Laravel/PHP, this is out of scope. (Your frontend, however, can be React or Vue rather than Livewire.)
• You need asynchronous post-upload processing. The v1.5.0 event is the clearest adoption trigger: if your backlog includes AI alt-text, moderation, transcoding, or indexing triggered by uploads, this release directly removes the "don't do that in the request" objection.
• Your picker lives somewhere lazy, or your API budget is tight. If the media picker will be mounted inside modals, drawers, tabs, or dashboard widgets, or if you have a stated goal of reducing requests on admin page load, v1.6.0's enabled option is a direct, low-effort win — and it applies equally in React and Vue.
• You are building controlled/custom media lists. If you drive fetching yourself (autoFetch: false) or run React StrictMode in development, v1.6.0 fixes the specific behaviors that otherwise force workarounds.
• Existing media libraries need a safe migration path. Versioned status columns plus the backfill command mean legacy rows can be reconciled deliberately. Worth adopting when you have a non-trivial existing corpus and no appetite for bespoke migration scripts.
• You want a status surface without building one. If a roadmap item is "show editors whether their images are optimized," the persisted status plus stable resource shape and TS types is close to a drop-in.
• You can accept the pipeline's definition of "optimized." The status reflects this package's processing service flipping state on success or failure. If you need fine-grained per-format, per-variant progress or retry orchestration, verify whether the single status field is sufficient before committing.
• You are prepared to own the upgrade. Confirm schema migrations are reviewed, queue workers are configured for ShouldQueue listeners, and the backfill command is run as part of deployment — not after.

Look elsewhere (or stay on a narrower vendor) when:

• A dedicated DAM/CDN already owns optimization and reporting — you would be duplicating state, and two sources of truth for "optimized" is worse than one imperfect one.
• You need synchronous, strongly consistent guarantees on optimization at upload response time; this is explicitly a queueable, eventual-consistency model.
• You need multi-tenant or per-tenant pipeline policies, custom format matrices, or SLA-tracked processing — validate against the package's extension points first, and assume you may be building alongside it.
• You cannot run queued workers in the environment (e.g., constrained serverless deployments) — the primary new capability is inert.
• You need a fully bespoke editor experience. The frontend is maturing fast — v1.6.0 is real investment in frontend correctness (fetch lifecycle, StrictMode, controlled mode), not cosmetic polish — but the modal and composables remain opinionated, and the hooks assume the package's /api/media shape. The escape hatch is now better (use the composables standalone with enabled / autoFetch and render your own UI), but if a deeply customized picker is a hard requirement, still budget design and frontend work, just less than before.

How to Pitch It (Stakeholders)

To executives (30 seconds): Two releases now cover both halves of the media story. v1.5.0 removed the main reason we would have delayed enrichment features: post-upload work — AI alt-text, moderation, indexing — runs in the background instead of slowing uploads, and every image carries a persisted "optimized / pending / failed" status with bytes saved. v1.6.0 fixes the admin side: the media picker no longer fires API requests until it is actually opened, so we can put it in dashboards and modals without a performance or infrastructure cost, and it works in both React and Vue. In practice: we can commit to media features without new infrastructure, we get a storage-savings metric for free, we cut wasted admin API calls, and upgrading an existing media library is a single command rather than a migration project.

To engineering leadership: v1.5.0 (unchanged, still the architectural anchor) adds a queueable MediaUploaded event dispatched from the single upload service that all entry points funnel through, so downstream packages subscribe with ShouldQueue listeners and stay off the request path; it persists optimization pipeline state on the media row (status, timestamp, bytes saved, original size, formats, error) and exposes a stable optimization block on MediaResource with matching TypeScript types, plus media:backfill-optimization-status to reconcile legacy rows. v1.6.0 is a frontend release with no breaking changes: useMediaPicker (React and Vue) gains an enabled option that defers initial media and recently-used fetches and then loads once — the Vue composable accepts a ref or getter — and MediaModal forwards its open state so a mounted-but-closed modal makes no /api/media requests; the list loads on first open, close/reopen does not refetch unchanged filters, and page changes or refresh() calls made while closed are applied on next open. It also fixes useMediaLibrary honouring autoFetch: false under React StrictMode re-runs and the Vue composable swallowing the first filter change when autoFetch is false. Separately, the release workflow now queues docs and changelog imports on the ArtisanPack UI docs site, skipped when DOCS_API_TOKEN is unset — worth noting for whoever owns the release pipeline, as it is a new external dependency in CI. Net risks remain: schema surface area, the operational requirement for queue workers and the backfill during rollout, and a fetch-on-open model that will read as "empty modal" if a consumer assumes eager loading.

To product/design: Editors get accurate optimization status in the media library UI (including a null-safe shape for non-image assets), pointer and keyboard affordance fixes, and — new in v1.6.0 — a picker that opens instantly with fresh data instead of pre-loading in the background, and that preserves filters and pagination across close/reopen so an editor does not lose their place. A status-badge and "storage saved" surface is now a small frontend task rather than a backend project, and adding the picker to a new screen is a cheap embed rather than an API-cost conversation — both worth slotting next to any existing media-management roadmap item.