Packagist · #984 most downloaded on Packagist

vich/uploader-bundle

v3.0.029M downloads/modustin10/VichUploaderBundle ↗New releases in your daily digest, changelog included.

Ease file uploads attached to entities

Last release 29 days ago
09 Sep 2026
Ships fairly regularly
a new release about every 2 months
Rarely documented
notes for 8 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
113 releases · first in 2012

Release timeline

113 releases since 2012

2012201420162018

Releases

v3.0.07 Sept 2026Deprecated
Annotations are gone. Only PHP attributes from Vich\UploaderBundle\Mapping\Attribute are supported. The deprecated Mapping\Annotation namespace, Annot…
First stable release of the 3.x line. It includes every fix shipped in 2.9.x and 2.10.0.
Upgrading from 2.x: read UPGRADE.md first.
2.x moves to maintenance on the 2.x branch.

Requirements

PHP 8.3 or newer. PHP 8.1 and 8.2 are no longer supported.

Symfony 6.4, 7.4 or 8.x. Symfony 5.4, 6.0 to 6.3 and 7.0 to 7.3 are no longer supported. (#1558)

Breaking changes

Annotations are gone. Only PHP attributes from Vich\UploaderBundle\Mapping\Attribute are supported. The deprecated Mapping\Annotation namespace, AnnotationInterface and the *Annotation() methods of AttributeReader are removed. (#1549, #1556)

NamerInterface::name() and DirectoryNamerInterface::directoryName() now take object|array. Custom namers type-hinting object must widen their signature. (#1561)

PropertyMappingResolverInterface::resolve() returns PropertyMappingInterface instead of PropertyMapping.

PropertyMapping, PropertyMappingFactory, MetadataReader and AttributeReader are final. Extend or mock the new interfaces instead: PropertyMappingInterface, PropertyMappingFactoryInterface, MetadataReaderInterface, UploadHandlerInterface. (#1539, #1565)

StorageInterface has a new listFiles(PropertyMappingInterface $mapping): iterable method, used by the cleanup command. Custom storages must implement it. (#1553)

Internal services use readonly classes and properties. Subclassing them was never supported and now fails at compile time. (#1568)

New

vich:cleanup command removes files in storage that no mapped entity references any more. Ships with --dry-run, a --min-age guard against in-flight uploads and an explicit confirmation step. See docs/command/cleanup.md. (#1553)

ChainDirectoryNamer concatenates the output of several directory namers. Empty segments are skipped. See docs/namers.md. (#1570)

Unique file names come from Random\Randomizer. (#1568)

Fixes carried over from 2.9.x and 2.10.0

Erasing file properties on delete only nulls properties that accept null. Non-nullable typed properties or setters no longer trigger a TypeError. (#1605)

resolveUri() normalises slashes between uri_prefix, directory and file name, so a trailing slash in uri_prefix no longer produces //. (#1604)

AttributeReader no longer instantiates attributes unrelated to the bundle. (#1603)

Concurrent uploads to the same new directory no longer fail on mkdir(). (#1589)

PropertyNamer and PropertyDirectoryNamer accept "0" as a value. (#1597)

VichFileType: delete_label keeps its own translation domain when download_label is a callable. New options download_label_translation_domain and delete_label_translation_domain. Custom form themes must read download_label_translation_domain instead of translation_domain for the download link. (#1574)

MappingCollector no longer breaks the profiler when no mapping data was collected. (#1594)

FileExtensionTrait no longer triggers the "null as array offset" deprecation on PHP 8.4. (#1595)

Internals

Container configuration is written in PHP instead of XML. (#1554)

declare(strict_types=1) removed to match the rest of the Symfony ecosystem. (#1600)

Test suite on PHPUnit 12, CI covers PHP 8.3 to 8.5 and Symfony 6.4 to 8.1. (#1560, #1596)

Changes since 3.0.0-rc4

Port of the fixes released on 2.x between 2.9.2 and 2.10.0 (#1574, #1580, #1594, #1595, #1597, #1603, #1604, #1605) and two doc updates (#1571, #1582).

Thanks

@endelwar, @gnat42, @guillaume-sainthillier, @ousamabenyounes, @sabat24, @Tairesh, @ixarlie, @theredled and @garak.

Full Changelog: v2.10.0...v3.0.0

One column per quarter.

v3.0.0-rc412 Aug 2026pre-release

Modernize Docker test images & fix PHP 8.3 / 8.5 by @endelwar in #1596

What's Changed

Modernize Docker test images & fix PHP 8.3 / 8.5 by @endelwar in #1596
port removal of strict_types to v3 by @garak in #1600
📝 Expand upgrade notes and fix some docs by @garak in #1601
fix gaufrette tests by @garak in #1606

Full Changelog: v3.0.0-rc3...v3.0.0-rc4

Open source →

v3.0.0-rc324 Jan 2026pre-release

Leverage PHP 8.2/8.3 features: readonly classes, readonly properties, and Randomizer by @Copilot in #1568

What's Changed

Leverage PHP 8.2/8.3 features: readonly classes, readonly properties, and Randomizer by @Copilot in #1568
add ChainDirectoryNamer directory namer by @guillaume-sainthillier in #1570

Full Changelog: v3.0.0-rc...v3.0.0-r3

Open source →

v3.0.0-rc217 Jan 2026pre-release

fix the "Non-readonly class PHPUnit\Metadata\DataProvider cannot exte… by @guillaume-sainthillier in #1572

What's Changed

fix the "Non-readonly class PHPUnit\Metadata\DataProvider cannot exte… by @guillaume-sainthillier in #1572
update directory_namer service id in doc by @guillaume-sainthillier in #1571

Full Changelog: v2.9.1...v3.0.0-rc2

Open source →

v3.0.0-rc20 Dec 2025pre-releaseDeprecated

Remove deprecated Annotation namespace by @endelwar in #1556

What's Changed

Support multiple extensions for MIME types in FileExtensionTrait by @endelwar in #1538
Add namer_keep_extension configuration option by @endelwar in #1540
Update PHPStan configuration and fix type issues by @endelwar in #1542
Add FileRequired validator constraint by @endelwar in #1541
Add interfaces for easier testing by @gnat42 in #1539
Remove support for annotations by @garak in #1549
Add cleanup command to remove orphaned uploaded files by @endelwar in #1553
Migrate configuration from XML to PHP by @endelwar in #1554
Remove deprecated Annotation namespace by @endelwar in #1556
Drop support for PHP < 8.3 and Symfony < 6.4 by @garak in #1558
PHPUnit 12 compatibility fixes and test refactor by @endelwar in #1560
update NamerInterface signature by @garak in #1561
remove bypass-finals by @garak in #1565

Full Changelog: v2.8.1...v3.0.0-rc

Open source →

v2.10.19 Sept 2026

Fix built-in namer configuration isolation for 2.10 by @endelwar in #1610

What's Changed

Fix built-in namer configuration isolation for 2.10 by @endelwar in #1610

Full Changelog: v2.10.0...v2.10.1

Open source →

v2.10.020 Aug 2026Deprecated

Fix "null as array offset" deprecation in FileExtensionTrait by @endelwar in #1595

What's Changed

Re-add MappingCollector null-safety by @endelwar in #1594
Fix "null as array offset" deprecation in FileExtensionTrait by @endelwar in #1595
Fix property namer empty check for "0" values by @sabat24 in #1597
🎨 remove strict type declarations by @garak in #1599
fix gaufrette dep by @garak in #1607
Normalize URI path separators by @ousamabenyounes in #1604
Fix unrelated attribute instantiation by @ousamabenyounes in #1603
🐛 Do not erase file properties when the entity is being removed by @ousamabenyounes in #1605

New Contributors

@sabat24 made their first contribution in #1597
@ousamabenyounes made their first contribution in #1604

Full Changelog: v2.9.4...v2.10.0

⚠️ Warning ⚠️

This will be the last minor release in branch 2.
Shortly, branch 3 will be merged into master, and the next release will be 3.0.0 (you can already try the next major version right now by requiring ^3.0-rc)

Open source →

v2.9.41 Jun 2026

Revert 3.x port leftovers and realign master with 2.9.2 by @endelwar in #1593

What's Changed

Revert 3.x port leftovers and realign master with 2.9.2 by @endelwar in #1593

Full Changelog: v2.9.3...v2.9.4

Open source →

v2.9.31 Jun 2026

This tag was mistakenly not containing all the needed fixes to keep BC. It lasted for a few hours, but if you got it, please upgrade to v2.9.4 as soon

⚠️ DO NOT USE ⚠️

This tag was mistakenly not containing all the needed fixes to keep BC. It lasted for a few hours, but if you got it, please upgrade to v2.9.4 as soon as possible.

What's Changed

Document issue with Gedmo\DoctrineExtensions by @craigh in #1582
Port latest master changes to 3.x branch by @Copilot in #1583
Restore master BC layer and legacy dependency/CI compatibility for annotation-to-attribute migration paths by @Copilot in #1590
Fix race condition in FileSystemStorage directory creation by @Tairesh in #1589
Restore other parts of master BC compatibility by @garak in #1592
CacheWarmer receives null instead of string during cache warmup by @ixarlie in #1588

New Contributors

@Tairesh made their first contribution in #1589
@ixarlie made their first contribution in #1588

Full Changelog: v2.9.2...v2.9.3

Open source →

v2.9.212 Mar 2026

fix the "Non-readonly class PHPUnit\Metadata\DataProvider cannot exte… by @guillaume-sainthillier in #1572

What's Changed

fix the "Non-readonly class PHPUnit\Metadata\DataProvider cannot exte… by @guillaume-sainthillier in #1572
update directory_namer service id in doc by @guillaume-sainthillier in #1571
🎨 fix coding standard by @garak in #1576
Fix VichImageTypeTest failing with LiipImagine enabled by @theredled in #1580
VichFileType : Fix translation for 'delete_label' when 'download_label' is a callable #1573 by @theredled in #1574

New Contributors

@theredled made their first contribution in #1580

Full Changelog: v2.9.1...v2.9.2

Open source →

v2.9.110 Dec 2025

Fix AttributeDriver not using Vich\UploaderBundle\Mapping\Annotation\UploadableField by @andyexeter in #1564

What's Changed

Fix AttributeDriver not using Vich\UploaderBundle\Mapping\Annotation\UploadableField by @andyexeter in #1564

Full Changelog: v2.9.0...v2.9.1

Open source →

v2.9.07 Dec 2025Deprecated

Deprecate Annotation namespace in favor of Attribute namespace by @endelwar in #1555

What's Changed

Support multiple extensions for MIME types in FileExtensionTrait by @endelwar in #1538
Add namer_keep_extension configuration option by @endelwar in #1540
Update PHPStan configuration and fix type issues by @endelwar in #1542
Add FileRequired validator constraint by @endelwar in #1541
Migrate configuration from XML to PHP by @endelwar in #1551
Deprecate Annotation namespace in favor of Attribute namespace by @endelwar in #1555
⬆️ allow Symfony 8 by @garak in #1524

Full Changelog: v2.8.1...v2.9.0

Open source →

v2.8.112 Sept 2025