Download the PHP package netbull/media-bundle without Composer

NetBull MediaBundle

A Symfony bundle for managing media — images, files and video providers (YouTube, Vimeo, Youku) — with pluggable storage (local filesystem or Amazon S3), thumbnail generation and configurable access-control strategies for downloads/views. Originally a trimmed fork of SonataMediaBundle.

• PHP: >= 8.3
• Symfony: 7.4 (LTS)

Installation

Register the bundle

With Symfony Flex this is automatic. Otherwise add it to config/bundles.php:

Import the routes

The download/view endpoints live in the bundle. Add to config/routes.yaml:

This registers netbull_media_view (/media/view/{id}/{format}) and netbull_media_download (/media/download/{id}/{format}).

Configuration

Create config/packages/netbull_media.yaml. A minimal local-development setup:

Each context declares which providers it accepts, its image formats, and the download/view security strategy. See docs/example_config.yaml for a full, annotated example (multiple contexts, S3, signed URLs, custom strategies).

Available services

Upload restrictions — each provider's allowed_extensions / allowed_mime_types are enforced on upload using the file's sniffed content (not the client-supplied name/type). A file is accepted only if it matches at least one of the configured lists.

S3 ACL — default to acl: private and serve public assets through the CDN; a public-read ACL makes objects world-readable and bypasses the bundle's download/view security strategies.

Secured downloads — for contexts behind a download/view security strategy, S3-backed media is served according to the context's download.mode / view.mode:

• stream (default) — the bytes are proxy-streamed through PHP in constant memory (lazy S3 GetObject, not the buffering Gaufrette adapter), returning a same-origin 200 so SPA clients can fetch it over XHR (no cross-origin redirect → no CORS).
• redirect — the client is sent a short-lived (300s) pre-signed S3 URL, so the file streams S3 → client and never passes through PHP (best for large files).

Local storage always streams the file in chunks. Either way the access-control check runs in the controller before the response is issued.

Video providers (SSRF) — video providers fetch oEmbed metadata and remote thumbnails over HTTP. Thumbnail URLs are validated before fetching (http/https to public hosts only; private, loopback and cloud-metadata addresses are refused) and redirects are disabled. To route this egress through your own controls, enable framework.http_client and the bundle will use the configured client.

Thumbnail generation (sync or async)

By default thumbnails are generated in-process when the media is flushed. To offload resizing to a worker, enable the async strategy:

Optional dependency — async mode needs the Messenger component, which the bundle treats as an optional (suggested) dependency. Install it before enabling async:

The message handler is only registered when symfony/messenger is installed, and enabling thumbnail.async: true without it fails fast with a clear error at container compile time. In the default sync mode the bundle works without Messenger.

When async: true, the bundle dispatches a NetBull\MediaBundle\Message\GenerateThumbnailMessage per format to the Messenger bus. Route it to an async transport so a worker does the resizing (worker recycling provides the memory isolation that long-running image processing needs):

With no transport routing configured, Messenger handles the message synchronously, so async mode is safe to enable before you have a worker.

Usage

Attach media to your entity

The bundle ships a mapped NetBull\MediaBundle\Entity\Media entity — reference it from your own entities:

Upload

Set the binary content and the provider/context, then persist. The bundle's Doctrine listener transforms the upload, stores it and generates thumbnails on flush:

In forms, use NetBull\MediaBundle\Form\Type\MediaType (or MediaShortType) with the provider and context options.

Render in Twig

The bundle registers these Twig filters:

Autowiring

Console commands

Development

License

MIT