Getting Started

Minimal Setup

Installation:

composer require sonata-project/media-bundle

Add to config/bundles.php:

return [
    // ...
    Sonata\MediaBundle\SonataMediaBundle::class => ['all' => true],
];

Database Setup: Run migrations for the MediaBundle:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

First Media Entity: Use the Media entity provided by the bundle:

use Sonata\MediaBundle\Model\MediaInterface;
use Sonata\MediaBundle\Model\MediaManagerInterface;

// In a controller or service
$mediaManager = $this->get('sonata.media.manager.media');
$media = $mediaManager->create();
$media->setProviderName('sonata.media.provider.image'); // Default provider
$media->setEnabled(true);
$mediaManager->save($media);

Upload Files: Use the Media form type:

use Sonata\MediaBundle\Form\Type\MediaType;

$form = $this->createForm(MediaType::class, $media);

Display Media: Twig template example:

{% for media in medias %}
    {{ sonata_media_embed_media(media, 'sonata.media.block.media', { 'width': 200, 'height': 200 }) }}
{% endfor %}

First Use Case: Blog Post with Images

Create a Post entity with a OneToMany relationship to Media:

/**
 * @ORM\OneToMany(targetEntity="Sonata\MediaBundle\Model\Media", mappedBy="context", cascade={"persist"})
 */
private $images;

Use the MediaType in your form to upload images:

$builder->add('images', MediaType::class, [
    'provider' => 'sonata.media.provider.image',
    'context' => 'blog_post',
    'multiple' => true,
]);

Implementation Patterns

Common Workflows

1. Media Providers

Default Providers: image, file, video, youtube, vimeo.

Custom Providers: Extend Sonata\MediaBundle\Provider\Pool and implement Sonata\MediaBundle\Provider\ProviderInterface.

class CustomProvider extends AbstractProvider
{
    public function generateUrl($media, $format = 'reference')
    {
        return '/custom/path/' . $media->getId() . '.' . $format;
    }
}

sonata_media:
    providers:
        custom:
            service: sonata.media.provider.custom

2. Media Contexts

Use contexts to organize media (e.g., blog_post, product).
Set context when creating media:
```
$media->setContext('blog_post');
```

3. Media Blocks (Admin UI)

Use Sonata Admin to manage media via the admin panel:

use Sonata\MediaBundle\Admin\MediaAdmin;

$adminPool->registerAdmin(MediaAdmin::class);

Customize the admin class to filter media by context:

protected function configureDatagridFilters()
{
    $this->datagrid->add('context', null, [
        'field_type' => 'string',
        'options' => ['eq' => 'blog_post'],
    ]);
}

4. Media Embedding in Twig

Use the sonata_media_embed_media Twig function:

{{ sonata_media_embed_media(media, 'sonata.media.block.media', {
    'width': 800,
    'height': 600,
    'autoplay': true
}) }}

Customize blocks by extending SonataMediaBundle:Block:block_media.html.twig.

5. Media Events

Listen to media events (e.g., sonata.media.pre_persist):

$eventDispatcher->addListener('sonata.media.pre_persist', function ($event) {
    $media = $event->getSubject();
    $media->setAuthor($this->getUser());
});

6. Media API (REST/JSON)

Use the built-in API endpoints:
- GET /api/media (list media)
- POST /api/media (upload media)

Customize routes in config/routes.yaml:

sonata_media_api:
    resource: "@SonataMediaBundle/Resources/config/routing/api.xml"
    prefix: /api

Integration Tips

1. Symfony Forms

Use MediaType for file uploads in forms:

$builder->add('thumbnail', MediaType::class, [
    'provider' => 'sonata.media.provider.image',
    'context' => 'product',
    'required' => false,
]);

2. VichUploaderBridge

Integrate with VichUploaderBundle for file handling:

# config/packages/vich_uploader.yaml
vich_uploader:
    db_driver: orm
    mappings:
        sonata_media:
            uri_prefix: /uploads/media
            upload_destination: '%kernel.project_dir%/public/uploads/media'
            namer: Vich\UploaderBundle\Naming\SmartUniqueNamer

3. Media in Entities

Reference media in your entities:

/**
 * @ORM\ManyToOne(targetEntity="Sonata\MediaBundle\Model\Media", cascade={"persist"})
 */
private $featuredImage;

4. Media in API Platform

Use ApiPlatform\Metadata\ApiResource with SonataMediaBundle:

#[ApiResource(
    operations: [
        new GetCollection(),
        new Post(
            normalizationContext: ['groups' => ['media:read']],
            denormalizationContext: ['groups' => ['media:write']]
        )
    ]
)]
class Product
{
    #[Groups(['media:read'])]
    #[Assert\Valid]
    private ?MediaInterface $image = null;
}

5. Media in Livewire/Alpine

Use Livewire to upload media dynamically:

public function uploadMedia()
{
    $media = $this->get('sonata.media.manager.media')->create();
    $media->setProviderName('sonata.media.provider.image');
    $media->setEnabled(true);
    $this->get('sonata.media.manager.media')->save($media);
    return $media;
}

Twig:

<livewire:media-uploader wire:model="post.images" />

Gotchas and Tips

Pitfalls

Provider Configuration:
- Issue: Forgetting to configure providers in sonata_media.yaml causes MediaNotFoundException.
- Fix: Ensure providers are registered:
```
sonata_media:
    providers:
        image:
            service: sonata.media.provider.image
```
File Permissions:
- Issue: Uploaded files fail with Permission denied errors.
- Fix: Set correct permissions for the upload directory:
```
chmod -R 775 public/uploads/media
chown -R www-data:www-data public/uploads/media
```
Context Mismatch:
- Issue: Media not appearing in the admin panel due to incorrect context.
- Fix: Verify context in the database and admin filters:
```
SELECT * FROM media WHERE context = 'blog_post';
```
CORS Issues:
- Issue: API uploads fail with CORS errors.
- Fix: Configure CORS in .env:
```
CORS_ALLOW_ORIGIN=^https?://yourdomain\.com$
```

Media Deletion:

Issue: Deleting a media entity doesn’t remove the file.

Fix: Implement a pre-remove event listener:

$eventDispatcher->addListener('sonata.media.pre_remove', function ($event) {
    $media = $event->getSubject();
    $provider = $this->get('sonata.media.provider.pool')->getProvider($media->getProviderName());
    $provider->delete($media);
});

Memory Limits:
- Issue: Large file uploads fail with Allowed memory exhausted.
- Fix: Increase upload_max_filesize and post_max_size in php.ini and set max_file_size in sonata_media.yaml:
```
sonata_media:
    max_file_size
```

Media Bundle Laravel Package