Media Bundle Laravel Package

Technical Evaluation

Architecture fit. The critical finding for a Laravel shop is that ranky/media-bundle is a Symfony bundle, not a framework-agnostic Composer package. Bundles depend on Symfony's kernel, bundle registration (config/bundles.php), DI container compilation passes, the config-tree/extension model, and — almost certainly — Doctrine ORM for metadata persistence and Symfony Security for authorization. None of those contracts exist in Laravel. A Laravel service container, Eloquent, and Laravel's routing/middleware stack cannot host this package without a port, and a port is a rewrite of the persistence and auth layers, not a configuration exercise. Fit is therefore high for a Symfony application, low for a Laravel application as an embedded dependency, and moderate-to-high as an adjacent HTTP service.

Integration feasibility. The realistic integration surface is the REST API, not the PHP code. If the API is versioned, documented, and auth-extensible, a Laravel app can treat MediaBundle as a media microservice: Laravel owns users, permissions, and business records; MediaBundle owns blobs, folders, variants, and the React admin UI. That is feasible and reasonably well-bounded. The integration work concentrates in four places rather than in media logic: (1) service-to-service authentication and tenant/ownership claims, (2) shared object-storage bucket layout and key naming so Laravel-generated URLs stay valid, (3) file-upload proxying vs. direct-to-service uploads, and (4) reconciling "media exists in MediaBundle" with "media is referenced in Laravel" when one side fails.

Technical risk. 68 stars and an opportunity score of 1.93 indicate thin adoption and weak ecosystem momentum — this is a small-audience project, likely with a narrow maintainer base. Principal risks: bus factor (single-maintainer abandonment means we inherit the fork), Symfony major-version upgrade cadence forcing us onto someone else's schedule, undocumented operational assumptions (image drivers, temp storage, upload limits, virus scanning), and admin-UI lock-in — the React front end is a separate build with its own npm dependency tree, so customizing it for our UX or i18n needs is real front-end work, not theming. Running two PHP runtimes and two framework dependency trees doubles our patch surface for a capability that is not our differentiator.

Key questions for the maintainer / spike.

• Is Doctrine ORM mandatory, or is there a storage abstraction seam (Flysystem/PSR-6/PSR-18) we could re-implement?
• Exact supported matrix: PHP versions, Symfony 6 vs 7, MySQL/Postgres, S3 vs local?
• How is API authentication implemented, and can it be swapped for OAuth2 client-credentials or JWT without forking? Is there a permission/voter model for per-tenant isolation?
• What is the API versioning and backward-compatibility policy? Are OpenAPI specs generated and tested?
• How are image variants generated — synchronous, Symfony Messenger, or external worker? What happens under backlog?
• Test coverage, CI matrix, static analysis level, and security disclosure process?
• Who are the maintainers, what is the release history cadence, and is any commercial support available?
• Does the React admin support SSO, audit logging, and role mapping, or would we front it with our own gateway?

Integration Approach

Stack fit. PHP-to-PHP is the only genuine advantage here, and it is a real one: no language boundary, shared Composer tooling, shared deployment primitives, and engineers who can read the source when the docs run out. But framework fit is the deciding factor, and it fails for embedded use. The pragmatic framing for stakeholders: we are not adopting a library, we are adopting a service. That reframing sets correct expectations on cost, ownership, and blast radius.

Decision rule. If requirements are "avatars, a few product images, thumbnails," stop — spatie/laravel-medialibrary is first-class Laravel, zero new runtime, and removes this entire risk register. MediaBundle only earns its keep if we need genuine DAM-shaped capability: folder hierarchies, tagging/search, a browsing admin UI, multi-variant generation, and an editorial workflow — and we are willing to operate a second service for it.

Migration path.

1. Timeboxed spike (1–2 weeks, one engineer). Bring the bundle up in docker-compose (Symfony app + DB + object storage), exercise the REST endpoints we actually need, and write a contract test suite against those endpoints. This is the go/no-go gate and the artifact that protects us later.
2. Auth bridge. Decide the trust model up front: signed service tokens from Laravel, or OAuth2 client credentials. Map our user/tenant model onto MediaBundle's notion of ownership. If it has no tenancy concept, this is a blocker, not a task.
3. Storage adapter and key-layout parity. Configure the backend to point at our existing bucket/prefix scheme so assets written by either side resolve. Validate signed-URL TTLs against our CDN.
4. Thin Laravel client. A MediaClient wrapper (HTTP client, retries with idempotency keys, timeouts, circuit breaker, typed DTOs). No Laravel code calls the raw API directly — this wrapper is what we can later re-point at a replacement.
5. Shadow phase. Dual-write new assets to both the existing path and MediaBundle in staging, run a reconciliation job comparing blob inventory to metadata records, and only then cut over reads.
6. Cutover and decommission the legacy upload path, with a backfill/migration job for historical assets and a documented rollback (keep the old write path warm for one release cycle).

Compatibility. Pin PHP and Symfony minor versions in the sidecar's own lockfile — do not let this service share a dependency resolution with the Laravel app. Verify storage-credential mechanism parity (IAM role vs. static keys), DB collation/encoding for filenames, and max upload size at the ingress layer.

Sequencing. Contract tests → tenancy/auth decision (blocking gate) → storage parity → Laravel client wrapper → admin UI evaluation (SSO, audit, branding) → observability → runbook → shadow → cutover. Front-load the auth/tenancy decision; it is the item most likely to invalidate the whole option and it is cheap to test early.

Operational Impact

Maintenance. Two runtimes, two dependency trees, two upgrade calendars, two CVE feeds. Symfony majors ship roughly every two years with a defined support window, so we inherit a forced upgrade cadence we do not control. Given upstream scale, plan for the realistic outcome that we become the de facto maintainer: budget a standing ~10–15% of one engineer for patches, upgrades, and the inevitable fork. Establish a written fork policy (private fork, patch branch, quarterly upstream rebase) before adoption, not after the first urgent CVE.

Support. No vendor, no SLA; GitHub issues constitute the support channel. Internal ownership must be explicit: a named team owns the sidecar, its on-call rotation, and its runbook. This is the single most common failure mode for "small dependency as a service" adoptions — it is nobody's job until it pages someone.

Scaling. The API tier is stateless and scales horizontally; the real constraints are elsewhere. Image variant generation is CPU-bound and will need a worker pool and a queue rather than in-request processing. Media traffic is I/O- and bandwidth-bound, so object storage plus a CDN in front is mandatory and largely determines unit cost. Metadata DB load stays modest. The failure point under growth is usually ingress on large uploads — plan a direct-to-storage or pre-signed upload path rather than proxying bytes through PHP.

Failure modes to instrument and rehearse.

• Media service down → uploads fail. Laravel must queue and retry with idempotency keys, and the user-facing path must degrade to "saved, processing" rather than erroring. Never make core business transactions synchronous on this service.
• Orphaned blobs / dangling references → metadata written, blob write failed, or the reverse. Needs a scheduled reconciliation job and a soft-delete grace period.
• Variant backlog → thumbnails missing while originals exist. Alert on queue depth and oldest-job age.
• Credential rotation on shared storage breaks one side silently. Rotate on a schedule and test both consumers.
• React admin build rot → an npm dependency tree that is nobody's sprint item accumulating known-vulnerable transitive packages. Add it to automated dependency scanning from day one.
• Transitive Symfony CVEs → subscribe to Symfony security advisories explicitly rather than relying on generic scanning.

Ramp-up. The team is Laravel-native; nothing here maps to muscle memory. Symfony's mental model (bundles, DI compilation, config trees, security voters, Doctrine mapping) plus a React admin we may need to modify represents a genuine 2–4 week ramp for one engineer just to be productive, and considerably longer to be safe in production. Budget for a deliberate knowledge-transfer: the spike engineer writes the runbook and does a walkthrough, and a second engineer is named as backup so the sidecar never has a bus factor of one — which would be an ironic outcome for a package we chose despite its own bus-factor risk.

Recommendation. Treat as conditional adopt, service-shaped: proceed only if the spike confirms a usable auth/tenancy seam and API stability; otherwise default to spatie/laravel-medialibrary and revisit when media requirements genuinely exceed what Laravel-native tooling covers.