Media Bundle Laravel Package

Getting Started

Reality check before you start. This bundle is archived (last release 2016-02-15) and marked EOL. It targets the Symfony 2.x/3.x era and a PHP 5.6/7.0 toolchain. Treat it as a component of an existing Elcodi application you are maintaining, not something to adopt on a greenfield project. If you are on a modern Symfony (5/6/7), the practical path is to lift the concepts and replace them — see the migration note in Gotchas.

Where to look first. The split repo here is read-only; the source of truth is the monorepo at github.com/elcodi/elcodi under src/Elcodi/MediaBundle. Read, in this order:

1. DependencyInjection/Configuration.php — the config tree tells you every knob (storage paths, image sizes, upload dir).
2. Resources/config/*.yml — service IDs and wiring; Elcodi leans heavily on named services and factories.
3. Entity/ and Entity/Interfaces/ — the media model and its contracts. The interfaces are what you should type-hint against.
4. The Factory and Repository classes — Elcodi's conventions are factory-created entities and repository methods, not raw new/find.

Install (legacy stack only). Pin an explicit tag — do not use dev-master, since the repo is frozen but the alias still resolves:

composer require elcodi/media-bundle:^1.0

Register it in AppKernel after the core Elcodi bundles, then import the bundle routing if you want its upload endpoints.

First use case. Attaching an image to a product: render a form with a file field → on submit, hand the UploadedFile to the bundle's media factory/uploader service → persist the resulting media entity → set it on the product via the media relation. Do this once end-to-end and read the uploader service to see exactly where the file is moved and named; that path is where 90% of your future debugging will happen.

Implementation Patterns

Use the factory + manager pattern, not new. Elcodi standardises on <Entity>Factory services and repositories. Inject the media factory and entity manager into your controller/service, call create(), then persist and flush. This keeps IDs, timestamps, and any listener-driven behaviour consistent.

Let the bundle own file movement. Rather than $file->move() in your controller, route uploads through the bundle's uploader service so naming, directory layout, and any image transforms stay in one place. Your controller becomes: validate → factory → uploader → persist → redirect.

Configure image variants, don't hardcode them. Put thumbnail/crop sizes in the bundle config (elcodi_media: section — verify keys against Configuration.php for your pinned version). Then render variants in Twig via the bundle's helper/extension instead of reconstructing paths by hand; hand-built paths break the moment the storage layout changes.

Associate media through the product/media interface. When wiring to elcodi/product-bundle, type-hint the media interface and use the relation setter so Doctrine's mapping and any cascade rules apply. Avoid storing raw path strings on your own entity — you lose the ability to regenerate derivatives later.

Override, don't fork. Elcodi bundles are designed for service overrides. To change upload behaviour, redefine the service ID in your app's services.yml (or decorate it), rather than editing vendor code — the split repo will never accept your patch anyway.

Use debug:container and debug:router as your map. Because documentation is thin and the bundle predates modern autowiring, the container dump is the fastest way to discover the actual service IDs available to you.

Gotchas and Tips

• EOL means no fixes. Security issues, PHP 8 incompatibilities, and Symfony deprecations will not be addressed. Budget for eventual replacement, not patching.
• Read-only split repo. The description says dependents: 0 and PRs are not attended — any change you make lives in your fork or in service overrides.
• dev-master alias is a trap. The README recommends it for "last commit," but on a frozen repo that just means an unpinned, moving target with no release discipline. Pin tags.
• Doctrine schema comes from the bundle. If you don't run the bundle's migrations or doctrine:schema:update, the media tables won't exist. Check the Entity/*.orm.xml mappings for exact table/column names before writing queries.
• Filesystem permissions bite first. Upload dir must be writable by the web user and consistent between CLI (workers, tests) and FPM. Most "media disappeared" reports are a var//web/ path or permission mismatch.
• Version drift between bundles. Elcodi bundles are co-released; mixing elcodi/media-bundle from one tag with elcodi/product-bundle from another is a common source of missing-method errors. Align versions across all elcodi/* packages.
• Interface vs. concrete class. Elcodi frequently exposes both MediaInterface and Media; hint the interface in your code so upstream class renames don't cascade into your services.
• Migration exit ramp. For new or modernised work, replace this bundle with VichUploaderBundle (upload lifecycle) plus LiipImagineBundle (derivatives) — the responsibilities map almost one-to-one, and both are actively maintained. Port your config-driven image sizes first; that's the piece with the least code and the most business value.