Getting Started

The fastest way to understand media-bundle is to wire one real media type end to end.

Recommended First Flow

Use this order:

configure filesystem storage
define one image type
upload a media entry with MediaTypeUploadType
render one configured version in Twig
open the admin media library only after the basic flow works

This lets you validate the real model before you add more formats, providers, or admin customization.

Example First Type

sfs_media:
    types:
        article_image:
            type: image
            name: 'Article image'
            upload_requirements:
                mimeTypes: ['image/jpeg', 'image/png', 'image/webp']
                minWidth: 1200
                minHeight: 675
            versions:
                card:
                    type: webp
                    scale_width: 480
                    webp_quality: 80
                article:
                    type: webp
                    scale_width: 1280
                    webp_quality: 85

This gives you:

one original upload
one smaller card version
one larger article version

Example Upload Form

use Softspring\MediaBundle\Form\MediaTypeUploadType;

$builder->add('heroImage', MediaTypeUploadType::class, [
    'media_type' => 'article_image',
]);

The form will create the _original upload field and any extra upload fields required by versions that define upload_requirements.

Example Twig Rendering

{{ media|sfs_media_render_image('article') }}

or, when you configure a picture set:

{{ media|sfs_media_render_picture('default') }}

When To Enable Admin Early

Enable the admin media library early when:

editors need manual upload and browse screens
you want a shared media library across several forms
you need modal media selectors in backoffice screens

If the project only needs one or two controlled upload flows, start with custom forms first and add admin later.

Common First Mistakes

installing the bundle but not defining any media type
importing admin routes but forgetting the role hierarchy import
expecting private media to come with signed URLs or delivery access control
treating video support as a transcoding system instead of a managed versioning and rendering layer