Media Bundle Laravel Package

Getting Started

rz/media-bundle is a thin Symfony 2-era extension for SonataMediaBundle, not a standalone media library. Treat it as a plugin you install alongside Sonata, not instead of it. Because the repo is archived, zero-star, and has no dependents, start by reading the source before running composer require — assume you may need to vendor/copy it rather than rely on it as a maintained dependency.

Minimal steps:

1. Confirm the era. Open composer.json and check the symfony/* and sonata-project/media-bundle constraints. This bundle targets Symfony 2.x; it will not resolve cleanly against Symfony 3.4+/4+ or modern Sonata (4.x/5.x) without patching. Pin your project to the matching Sonata version or expect conflicts.
2. Install and register. Add the dependency (likely dev-master from the archived repo), then register new RZ\MediaBundle\RZMediaBundle() in AppKernel.php. Registration order matters: it must come after SonataMediaBundle, SonataAdminBundle, and SonataCoreBundle, since it extends their services and templates.
3. Configure Sonata first. A working sonata_media config (db driver, default context, filesystem/ Imagine adapters) is a prerequisite. This bundle's config tree usually adds contexts, providers, or template overrides on top — it does not replace the base setup.
4. Look here first:
   • DependencyInjection/Configuration.php — the real contract; tells you what config keys it expects.
   • DependencyInjection/*Extension.php and Resources/config/*.xml — which Sonata service IDs it decorates/overrides.
   • Any Provider/ classes — likely BaseProvider subclasses registering new media types.
   • Resources/views/ — template overrides applied to Sonata admin/media rendering.
5. First use case: wire it into an existing SonataMedia install, clear cache, and verify in the Sonata admin media list that the bundle's provider/context appears and uploads succeed. If you have no SonataMedia install yet, build that baseline first — debugging two unknown layers at once is painful.

Implementation Patterns

Treat it as a Sonata extension layer. The day-to-day workflow is: keep SonataMediaBundle as the media engine, and let this bundle contribute providers, contexts, admin tweaks, or templates. Don't route core media CRUD through it independently.

• Config-driven contexts. Define contexts in config.yml under sonata_media.contexts and let this bundle's config add its own providers/formats. Contexts map to upload dirs and Imagine formats; keep them small and explicit (e.g., default, news, avatar) and align formats with LiipImagine/Imagine filter sets.
• Provider extension. If the bundle ships a custom provider, register it via sonata_media.providers.<name> and reference it in a context. To add behavior without forking, subclass its provider and override getProviderMetadata()/buildMedia/postPersist, then swap the service ID in your app config.
• Template overriding. Prefer Symfony resource overriding (app/Resources/RZMediaBundle/views/...) over editing vendor files. If it overrides Sonata templates, check Resources/views/ for the exact path and Twig block names — override at the most specific bundle level so Sonata upgrades don't silently break you.
• Service decoration. For cross-cutting changes (e.g., adding a filename sanitizer or storage path rule), decorate Sonata's sonata.media.provider.* or filesystem services with a compiler pass rather than patching this bundle. This keeps the archived code untouched.
• Admin integration. Extend Sonata admin classes (or the bundle's admin if defined) and register via sonata_admin. Configure form fields for media selection using Sonata's sonata_type_model_list / media type, ensuring the bundle's provider is selectable.
• Testing loop. Use a Sonata sandbox or a functional test that (a) boots the kernel with both bundles, (b) uploads a file through a provider, (c) asserts the media entity and generated thumbnail formats. This catches service-ID and config drift early.
• Migration path. Since maintenance is dead, plan to either pin the whole Sonata stack to the compatible era, or extract the useful provider/config/templates into your app and drop the bundle. The latter is usually cheaper for new projects.

Gotchas and Tips

• Archived = dependency drift is the main risk. SonataMediaBundle changed namespaces, service IDs, and config keys across major versions. Any upgrade of Sonata will likely break this bundle silently (missing service, ignored config key). Always diff container:debug output against expected service IDs after an upgrade.
• Bundle order is not optional. Registering before Sonata produces confusing "service not found" or template-not-overridden errors. Put it last in the relevant block of AppKernel.
• Config keys can be silently ignored. If a config key isn't consumed by the extension, Symfony may not complain (depending on version/strictness). Verify effects in container:debug / debug:config rather than trusting that YAML "took."
• Upload/storage permissions. Sonata media writes to web/uploads/media (or configured adapter). Ensure the web server user can write, and confirm the bundle doesn't add a second, divergent upload path in its config.
• Cache is your enemy when debugging. After changing providers, contexts, or templates, always cache:clear (and warm up) — service definitions and Twig overrides are compiled.
• Service ID collisions. A thin extension often redeclares or aliases Sonata IDs. Use debug:container <id> and check for overridden definitions; a stray override can change behavior far from where you edited.
• Thumbnails need Imagine config. If images render but derivatives 404, the issue is usually missing LiipImagine/Imagine filter definitions matching Sonata formats, not this bundle. Verify formats resolve to actual filters.
• Zero dependents / zero stars is a signal. Audit the code for hardcoded paths, debug dump() calls, and missing tests before adopting. Read every PHP file — it's small — rather than assuming standard Symfony conventions.
• Extension points that survive: custom BaseProvider subclasses, event listeners on Sonata media events, Twig template overrides, and service decoration. Prefer these over editing the bundle so you can remove it cleanly later.
• Debugging checklist: debug:container | grep -i media, debug:config sonata_media, check sonata.media.provider.* tags, confirm the provider appears in admin media create form, then test upload + thumbnail generation end-to-end.