Weave Code
Media Bundle Laravel Package
softspring/media-bundle
Softspring MediaBundle is a Symfony bundle for managing uploaded media files and images, with Doctrine-backed media entities, configurable storage and upload handling, plus helpers for integrating and rendering media assets in your applications.
A media management bundle
Frequently asked questions about Media Bundle
- Is softspring/media-bundle compatible with Laravel?
- No. It is a Symfony bundle that depends on Symfony's service container, Doctrine entity mappings, and Twig/asset integration, none of which map cleanly onto Laravel's service providers, Eloquent, or Blade without a substantial adapter layer. If your application is Laravel, the correct move is to evaluate a Laravel-native media library instead of forcing an adapter around this bundle. Only proceed if the consuming application is genuinely Symfony-based.
- How do I install softspring/media-bundle?
- Install it with Composer and register the bundle in your Symfony application's bundle configuration, then configure your storage adapters and media types. Because the package ships Doctrine-backed media entities, you also need to run the provided migrations so the media and media version tables exist. Confirm the exact Symfony and Doctrine version constraints in the package's composer.json before committing, since constraints differ between major lines.
- How do I attach media to a Doctrine entity?
- You attach media by configuring relations between your domain entities and the bundle's media entity, so images and documents live outside your domain logic. The relations are configurable, which means you decide which entities own media and how collections are exposed. This keeps storage and processing concerns separate from your business model and lets one entity hold many assets.
- How do I configure storage and upload handling?
- Uploads and file storage go through storage adapters, so you configure where files physically live while the bundle handles the upload flow. Paths, media types, and processing options are all configurable rather than hardcoded. For most projects you start with a local filesystem adapter and swap in a remote or custom adapter later if you need one.
- Can I generate thumbnails and image variants with this bundle?
- Yes. Image variants and thumbnails are produced through configurable filters, so you define the sizes and transformations you need and the bundle generates and stores the resulting versions. Each generated version is tracked as a media version record, which is why schema changes to that table matter during upgrades. You can then render the appropriate variant per context in your templates.
- Which Symfony versions does softspring/media-bundle support?
- The 5.x line, including the v5.6.0 release, targets Symfony 5.x and 6.x applications that are already running the bundle. Always verify the supported Symfony and PHP ranges in the package's composer.json rather than assuming, because minor releases can tighten constraints. If you are on an older Symfony version, check the constraint before upgrading.
- What changed in v5.6.0 and is the upgrade safe?
- Version 5.6.0 adds a public URL filter for media versions, which is additive and low risk, and it adds a unique index on MediaVersion along with duplicate prevention in migrations. The URL filter is the easy part; the index is a schema-level change, so the upgrade is not a pure Composer bump. No deprecations or breaking API changes are signalled, but the release notes are terse, so review the full changelog before sign-off on a production system.
- Will the unique index migration fail if I already have duplicate MediaVersion rows?
- It can. Adding a unique index will fail on any database that already contains duplicate MediaVersion records, which is exactly the class of problem the release's duplicate-prevention wording hints at without guaranteeing your data is clean. Run a read-only duplicate audit against staging and a production clone before scheduling the upgrade. If duplicates exist, build and rehearse a remediation script in staging rather than trusting the package migration to decide which rows survive, since deleting the wrong row can break media references.
- How should I test media uploads and image processing before upgrading?
- Exercise upload, variant generation, and rendering in a staging environment that mirrors production data, using functional tests against a test database for the core flows. Validate that existing media URLs still resolve and that representative content renders correctly after the migration. Also check the migration's behaviour on large tables, because online DDL, table locks, and blocking rewrites differ materially between MySQL and Postgres.
- What are the alternatives if my project is Laravel-based?
- For Laravel, re-scope the evaluation against a Laravel-native media library such as Spatie's laravel-medialibrary or an equivalent package that integrates with Eloquent and the filesystem abstraction out of the box. Those libraries give you uploads, conversions, and media attachments without an adapter layer around Symfony internals. Keep softspring/media-bundle on the shortlist only for Symfony applications already running its 5.x line.
Weaver
How can I help you explore Laravel packages today?