Concepts
The bundle revolves around three runtime concepts:
- the media entity
- the media version entity
- the media type configuration
Media Entity
MediaInterface represents the logical media entry. It stores:
- type key such as
article_image - normalized media category such as image or video
- name and description
- privacy flag
- SHA-1
- translated alt texts
- all versions
The media entry is the stable business object. Versions are derived or uploaded files attached to it.
Media Version Entity
MediaVersionInterface represents one stored or generated file version.
It stores metadata such as:
- URL
- mime type
- dimensions
- file size
- upload or generation timestamps
- normalized options
- SHA-1
_original is the special original uploaded file. Every media has one.
Generated And Uploaded Versions
Configured versions are either:
- generated versions
- derived automatically from another version, usually
_original
- derived automatically from another version, usually
- uploaded versions
- require their own upload because they define
upload_requirements
- require their own upload because they define
This distinction matters for migrations and admin flows.
Processing Pipeline
The version lifecycle is driven by Doctrine listeners and tagged processors:
UploadedImageSizeProcessorVersionFileCopyProcessorImagineProcessorStoreFileProcessor
That means version generation is part of the entity lifecycle, not a separate batch command you must call manually after every upload.
Migration When Type Config Changes
When type definitions change, old database rows and stored files do not update automatically.
Use:
php bin/console sfs:media:types-migration
The migration logic classifies versions as:
oknewchangeddeletemanual
That is what lets the bundle regenerate generated files while preserving manual-upload expectations.
Duplicate Detection
MediaManager also includes duplicate helpers based on:
- media type
- SHA-1 of the original version
This is useful when cleaning or consolidating large media libraries.
Important Current Limitations
- video support is rendering- and storage-oriented, not a transcoding pipeline
- private media is a persisted flag, not a complete secure delivery system
- some rendering paths still assume the default filesystem public URL behavior
These are not reasons to avoid the bundle. They are integration details you should understand before depending on those behaviors.