Image Bundle Laravel Package

Getting Started

VichUploaderBundle is a Symfony/Doctrine bundle, not a Laravel package — there is no service provider, no config/vich_uploader.php to publish, and no facade. If you are in a Laravel codebase, the first thing to confirm is whether you actually need it (you almost certainly want spatie/laravel-medialibrary or a small custom upload service instead). If you are in a Symfony app, or a mixed repo, proceed:

1. composer require vich/uploader-bundle:^3.0 — 3.0.0 is the first line that targets Symfony 5.1+, so this is a hard floor, not a suggestion. Verify the transitive constraints before bumping.
2. Register the bundle in config/bundles.php (Symfony) and create config/packages/vich_uploader.yaml with db_driver: orm and at least one named mapping (upload_destination, uri_prefix, namer, directory_namer).
3. Mark your entity with #[Vich\Uploadable], add the Vich\UploadableTrait, one #[Vich\UploadableField(mapping: '...', fileNameProperty: 'imageName')] property holding the File/UploadedFile, and a string property for the stored filename.
4. First use case: a single avatar/image field. Persist the entity, call setImageFile($uploadedFile), set updatedAt, then flush(). The bundle's Doctrine listeners handle upload-on-persist, expose-on-load, and delete-on-remove.

Implementation Patterns

• Form-driven uploads. Use VichImageType / VichFileType in your form class; they render the current file link plus the upload input and wire the *File property without manual plumbing.
• Manual uploads in a service. For API endpoints, set the file property, touch the timestamp property, persist() + flush(). Keep this in a dedicated service if you need post-upload processing (thumbnails, virus scan, DB transaction wrapping).
• Multiple mappings per entity (e.g. avatars and documents) is the standard way to get different destinations, namers, and URI prefixes; don't overload one mapping with conditionals.
• Namer strategy is where the leverage is: property namer keeps the client filename (friendly URLs, collision risk), hash namer is the safe default for user content. Pair with directory_namer (date or entity-id subdirectories) to avoid single-directory blowups on object storage.
• Deletion is declarative. Set the file property to null (or call removeFile) and flush — the delete_on_update option removes the old file. No manual unlink() in most cases.
• Storage abstraction. Swap the vich_uploader.storage service to an S3/GCS adapter so the same entity code works across environments; keep uri_prefix environment-specific (CDN in prod, local path in dev).
• Download/render. Read the filename property and build either a StreamedResponse from the storage service or an asset URL. Never expose the raw binary property on a JSON resource — serialize only the filename/URL.
• Testing. In config/packages/test/vich_uploader.yaml, point upload_destination at a temp dir and set storage: vich_uploader.storage.file_system; assert on the filename property rather than filesystem bytes.

Gotchas and Tips

• The biggest gotcha is the framework mismatch. This bundle is Doctrine-event driven. It does nothing for Eloquent models, and there is no Laravel package discovery. Any "install into Laravel" plan needs a Doctrine bridge first — usually a signal to pick a different package.
• updatedAt must actually change. The update listener only fires when Doctrine detects a dirty entity. If a user replaces a file, call setUpdatedAt(new \DateTime()) yourself or the new upload is silently skipped. This is the number-one bug report for the bundle.
• inject_on_load injects a file object on postLoad; it breaks serialization and some form re-renders. Enable it only where you need it, and exclude the *File property from your serializer groups.
• Orphans on failure. The upload happens in a Doctrine lifecycle event; if the flush fails afterwards, the file stays on disk. Wrap manual uploads in try/catch with cleanup, or run a periodic sweeper.
• Upgrading to 3.0.0 is a hard break in constraints, not an API break. Budget time for Symfony/Doctrine/PHP bumps across the app and third-party bundles that pin vich/uploader-bundle ^2.x. If you're on Symfony 4.4, stay on 2.x — 3.0.0 will not resolve.
• Deprecation sweep. Major versions typically drop annotation-only metadata in favour of attributes and remove long-deprecated setters/getters. Grep your entities for annotations and for any Vich\UploaderBundle\Mapping\Annotation imports before upgrading.
• Debugging: bin/console debug:container vich_uploader to confirm the configured mappings and storage service, and bin/console debug:event-dispatcher to verify the listeners are registered — a missing vich_uploader.yaml section fails silently as "no upload happened."
• Extension points: custom namers (Vich\UploaderBundle\Naming\NamerInterface), directory namers, and custom storage adapters are the supported seams. Prefer a namer over a Doctrine event subscriber that post-processes filenames — subscribers run outside the bundle's ordering guarantees.