Filament Media Library Laravel Package

Technical Evaluation

Architecture fit. The package occupies the media path of a Laravel application: upload ingestion and sanitization, a storage/library layer, and a field-based picker surface rendered in the admin UI. v0.4.0 does not move that architecture; it consolidates three previously scattered concerns into single owners — Drop intake (all three drop surfaces plus the inline trigger and both tabs), Card painting (thumbnail, BlurHash, hash painting, in-flight state, once per field and once per asset), and TenantReach (the single answer to "may this field context attach these ids", shared by picker validation and AttachmentReconciler). From a TPM standpoint the release is a cohesion release with one security-driven forced upgrade and several behavioral convergences, not a re-platforming. That is a favourable shape: the integration seam (the field's own configuration) is explicitly unchanged.

Integration feasibility. Composer-level integration is trivial — one dependency constraint moves from enshrined/svg-sanitize ^0.22 to ^1.0, and there are no stated migrations or config changes. The real integration work is behavioral: (a) some SVGs that uploaded cleanly now get refused, (b) an attach path that previously surfaced a database foreign-key error now surfaces AttachRefused, and (c) five public-ish methods disappear (MediaPicker::upload(), LibraryGrid::thumbnailUsing(), pollable(), isPollable(), MediaPicker::getThumbnailUrl(), paintsThroughPipeline()). Each is a bounded, greppable change, but each can be a fatal error or a silent behavior shift in consumer code rather than a compile-time failure.

Technical risk.

• Highest: the sanitizer upgrade does not remediate SVG bytes already at rest. Anything stored under 0.22 retains whatever 0.22 produced, including content that the four now-published advisories describe. The package deliberately does not re-sanitize at rest. Upgrading the library closes the forward path and leaves the historical exposure open until assets are re-uploaded or re-encoded. Treat the dependency bump and the content backfill as two separate workstreams with separate owners.
• Supply-chain blind spot: composer audit reported clean against 0.22.0 throughout because Packagist had not ingested the advisories. Our SCA signal was green while four exploitable classes were open. That is a process finding as much as a package finding.
• Behavioral regressions: dropping a picture onto a filled single-image field now replaces rather than refusing — arguably the right default, but it is a destructive action newly enabled on the most-used surface, with no stated opt-out. Field authors who relied on thumbnailUsing() being consulted for non-image assets lose that; the release itself flags this as the reason it is a minor rather than a patch.
• Exception-surface change: applications with no tenant resolver now receive AttachRefused where a query exception previously surfaced. Any catch (QueryException) around attach code becomes dead, and any generic handler that logged-and-continued will now see a domain exception instead.
• Refusal breadth: remote-reference detection now reaches bare remote href/src, unquoted url(), url() among other declarations in a style attribute (dropping the whole attribute, not the declaration), and remote @import/url() inside <style> text. The blast radius on a real icon/illustration library is unknown until measured.

Key questions.

1. What is the documented public API, and were the five removed methods ever documented or recommended for extension? The release leans on a "promised surface" definition — we should get that written down and versioned, because it is the contract we will be held to at the next minor.
2. How many stored SVGs reference custom entities or remote references, and what is the inventory count by tenant/site?
3. Do we have a supported re-sanitization path (a command, a job, a re-upload UX) for existing assets, or must we build one?
4. Does enshrined/svg-sanitize 1.0 raise the PHP floor or change its own public API in ways that constrain our runtime matrix?
5. Is AttachRefused catchable via a stable base type, and does it implement a marker interface? The release promises both named constructors are caught together — confirm that holds for our handlers.
6. What is upstream's maintenance cadence and release discipline, given that four advisories sat unpatched across an entire 0.x line and only surfaced on the repository, not in the advisory database?
7. Is there an opt-out or per-field configuration for replace-on-drop, and for Strict-pass placement?

Integration Approach

Stack fit. Standard Composer/Laravel dependency; no new infrastructure, no queue or storage changes, no migration. The field-configuration API — the surface field authors actually write — is unchanged, so existing field definitions, templates and picker registrations need no edits. The release is pre-1.0, so a minor carrying behavior changes is within the project's stated contract, but our change-advisory process should not treat it as routine.

Migration path.

1. Branch upgrade; resolve svg-sanitize ^1.0; verify PHP floor and lockfile diff.
2. Grep the application for the five removed methods and for subclasses of LibraryGrid / MediaPicker; any override of those methods is a hard break.
3. Grep for catch (QueryException) and catch (\Illuminate\Database\... around attach, seed, job and import paths; widen to AttachRefused where the old behavior was "let the DB refuse".
4. Build an SVG fixture set (custom-entity reference, remote bare href, unquoted url(), style with mixed declarations, remote @import in <style>, mixed-case xlink:HrEf, element-dense document) and assert refusal/preservation behavior on staging before rollout.
5. Inventory stored SVGs; decide per-asset whether to re-encode to raster, re-export without the entity/remote reference, or re-upload.
6. Ship with an editor-facing note explaining the new refusal reasons and the remedy.

Compatibility. No schema or config delta expected. Runtime compatibility risk is confined to (a) PHP/dependency floor from the sanitizer major, (b) consumer code touching removed methods, (c) exception handling around attach paths. Behavior compatibility is not guaranteed for uploaded content or for non-image assets in custom-thumbnail fields.

Sequencing. Do the code inventory and the fixture tests first (day 1–2, cheap, catches the fatal-error class). Deploy the dependency bump to staging, then to production behind normal release process. Run the content inventory in parallel but land the backfill as a separate, tracked remediation with its own acceptance criteria — do not let the green build imply the stored-asset exposure is closed. Editor comms go out before the deploy, not with it.

Operational Impact

Maintenance. We inherit a ^1.0 major constraint on a security-critical transitive dependency, which is the correct posture — the release explicitly refuses to leave 0.22 resolvable, and that decision should be preserved rather than "widened for flexibility" by a future maintainer. Add upstream-repository advisory watching to the dependency-review routine, because composer audit demonstrably lagged here; a clean audit is no longer sufficient evidence.

Support. Expect a bounded wave of "my SVG won't upload" tickets from editors and designers. The refusal names the file, which is good, but the remedy (re-export without the custom entity, make the remote reference local) needs to be in the help text and in the ticket macro. Separately expect questions about images disappearing from cards in fields with a custom thumbnailUsing() rule — that is a deliberate convergence, and it should be documented as such rather than handled ad hoc.

Scaling. Two real wins. The quadratic-to-linear sanitization on element-dense SVGs removes a CPU-exhaustion vector on the upload path, which matters if uploads are synchronous in the request cycle. The Upload tab's new room check stops over-capacity confirms from uploading assets that then sit unattached in the library — fewer orphans, less storage drift, less cleanup. Unifying reconciliation under TenantReach means a rule change propagates to both the picker and programmatic attach paths, which is the difference between one policy and two that can drift.

Failure modes.

• Fatal Error: Call to undefined method in any consumer overriding or calling the removed methods.
• Uncaught AttachRefused in queued jobs, seeders and imports that previously relied on a database error; these can become retry loops rather than clean failures if the handler treats unknown exceptions as retryable.
• Legacy stored SVGs remaining exploitable despite a "security release" being applied — the most likely misunderstanding.
• Silent content loss if a save is attempted on a host record whose picked asset was soft-deleted (now fixed, but confirm the fix is what actually ships) and silent replacement of a cover image on drop (now intended, but destructive).
• Attachment rows now legally outliving their assets; verify Delete/restore and any reporting that joins attachments to assets handles the soft-deleted case.

Ramp-up. Low for field authors — configuration is untouched. Low-to-medium for application developers — mostly inventory work against a short, greppable list. Medium for editors and designers, who must learn a new refusal class and the re-export remedy, and medium for whoever owns the stored-asset remediation, since that work has no tooling and no automatic path by design.