Media Bundle Laravel Package

Getting Started

This package is a read-only subtree split of the main enhavo/enhavo repository. The README is not a usage guide — it only points back to the monorepo. Treat the repository itself as the documentation: open composer.json, src/, DependencyInjection/, Resources/config/, and Entity/ first.

Minimal activation:

composer require enhavo/media-bundle

// config/bundles.php
return [
    // ...
    Enhavo\Bundle\MediaBundle\EnhavoMediaBundle::class => ['all' => true],
];

Then inspect the bundle's service definitions and routing:

php bin/console debug:container | grep -i media
php bin/console debug:router | grep -i media

Look first for:

• Entity/ or Model/ — the media/file abstraction (File, Image, Video, Audio or similar).
• Form/Type/ — the upload form type you will embed in your own admin forms.
• Controller/ — upload/download endpoints and their route names.
• Resources/config/ — services, Doctrine mappings, and routing.
• Admin/ — Enhavo's admin resource configuration if you are using the CMS admin.
• Twig/ — URL/thumbnail helpers for rendering media in templates.

A sensible first use case: attach a media entity to one of your own Doctrine entities, upload it through an admin form, and render its public URL and a thumbnail in Twig. That exercises the full path — storage, metadata, entity association, and rendering — before you customize formats or storage.

Implementation Patterns

Entity association. The common pattern is a ManyToOne (or OneToOne) from your domain entity to the bundle's media entity. Persist the association, not the raw file path, so the bundle remains responsible for storage and URL resolution.

#[ORM\ManyToOne(targetEntity: Media::class)]
private ?MediaInterface $image = null;

Confirm the exact interface/class name from src/ before writing mappings — the bundle distinguishes media types, so you may need FileInterface rather than a concrete class.

Form integration. Embed the bundle's media form type in your own Symfony form and let it handle upload and existing-media selection:

$builder->add('image', MediaType::class, [
    'required' => false,
]);

In the admin context, Enhavo's resource/admin configuration is usually the better integration point than hand-rolling forms. Check Admin/ for how the bundle registers media as an admin resource, then mirror that pattern for your own resources.

Programmatic uploads. For imports or API endpoints, inject the bundle's media manager service, create a media object from a UploadedFile or local path, persist it through the manager, and flush. Prefer the manager over manually moving files — it centralizes filename generation, metadata, and storage abstraction.

Rendering. Use the Twig extension rather than concatenating upload paths. Typical usage looks like:

<img src="{{ media_url(entity.image) }}" alt="">
<img src="{{ media_url(entity.image, 'thumbnail') }}" alt="">

Verify filter/format names against Resources/config/ and any LiipImagine (or equivalent) configuration. The same applies to download links and video/audio rendering: use the bundle helper so storage changes do not break templates.

Formats and media types. The bundle is designed around media formats (image sizes/variants) and type-specific behavior. Add project-specific formats in bundle configuration or by extending the relevant services, rather than hardcoding dimensions in templates. If you need a new media type, look for the type registry/resolver and register a new service tagged the same way as the built-in image/video/audio types.

Admin workflow. Media is typically managed as its own admin resource (upload, list, edit metadata), then selected from other resources via the media form type. Use that two-step workflow instead of embedding raw uploads everywhere; it gives you a reusable media library and consistent permissions.

Gotchas and Tips

• Read-only split. Do not open pull requests against this repository. Changes belong in the main Enhavo monorepo and are split back here. Pin a specific version and track the main repo for changelogs.
• Maturity risk. Two stars, zero dependents, and a README-only score mean you should budget time to read the source. There is no meaningful standalone documentation; the main Enhavo repo and its demo/application code are your real references.
• Doctrine mappings and migrations. Confirm whether the bundle ships XML/YAML/PHP mappings and whether you need to generate migrations for the media tables. Do not assume doctrine:schema:update is acceptable in production; generate and review migrations.
• Filesystem configuration. Upload directories must be writable by the web server and, if served directly, web-accessible. Check how the bundle resolves public URLs versus internal storage paths — these are often different settings.
• Thumbnail generation requires a filter library. If image variants depend on LiipImagine or a similar service, a missing filter configuration usually shows up as a 404 or a broken image rather than a clear exception. Run debug:config for the relevant bundle and check the generated cache directory.
• Service and route name collisions. The bundle uses the enhavo_media namespace by convention. When overriding templates or services, use the full bundle path (e.g. templates/bundles/EnhavoMediaBundle/...) and verify overrides with debug:twig or debug:container --show-private.
• Storage abstraction is the extension point. If you need S3, CDN URLs, or custom naming, look for the storage/resolver interface and decorate or replace that service rather than patching controllers.
• Events and lifecycle. Check for Doctrine listeners or bundle events around file persistence and deletion. Orphaned files after entity deletion are a common failure mode — wire cleanup explicitly if the bundle does not do it for you.
• Template overrides are version-sensitive. Because the bundle is tightly coupled to the CMS admin UI, a minor Enhavo upgrade can change template blocks. Keep overrides minimal and re-test after upgrades.
• Debugging checklist. When media does not render: verify the entity association is flushed, check the resolved URL with debug:router, inspect the upload directory permissions, and confirm the media format/filter exists. When uploads fail silently, check form validation constraints and the manager service's exception handling.