📝 Expand upgrade notes and fix some docs

Author: garak

UPGRADE.md

@@ -2,9 +2,15 @@
 
 ## Breaking Changes
 
+* Minimum PHP version raised from `^8.1` to `^8.3`.
+* Minimum Symfony version raised: support for `5.4` and `7.0`-`7.3` has been dropped. Symfony `6.4`, `7.4` and `8.0` are now required.
 * The deprecated `Vich\UploaderBundle\Mapping\Annotation` namespace has been removed. Use `Vich\UploaderBundle\Mapping\Attribute` instead.
 * The deprecated `AnnotationInterface` has been removed. Use `AttributeInterface` instead.
+* Support for annotations has been removed entirely). Use PHP attributes instead.
 * `AttributeReader` deprecated methods have been removed: use `getClassAttribute()` instead of `getClassAnnotation()`, `getPropertyAttribute()` instead of `getPropertyAnnotation()`.
+* `NamerInterface::name()` and `DirectoryNamerInterface::directoryName()` parameter type widened from `object` to `object|array`. Custom namers that type-hint the parameter as `object` must update their signature to match.
+* `PropertyMappingResolverInterface::resolve()` (and the `PropertyMappingResolver` implementation) now returns `PropertyMappingInterface` instead of the concrete `PropertyMapping` class. Code that type-hints against `PropertyMapping` directly should switch to `PropertyMappingInterface`.
+* Several internal classes are now `final` and are only meant to be extended through interfaces: `PropertyMapping`, `PropertyMappingFactory`, `MetadataReader` and `AttributeReader`. New interfaces are provided as extension points: `PropertyMappingInterface`, `PropertyMappingFactoryInterface`, `MetadataReaderInterface` and `UploadHandlerInterface`. Code that extended or mocked these concrete classes should depend on the corresponding interface instead.
 
 # Upgrading from v2.8 to v2.9
 

docs/configuration_reference.md

@@ -21,7 +21,7 @@ vich_uploader:
             directory_namer: ~           # specify a directory namer service for this entity, null default
             delete_on_remove: true       # determine whether to delete file upon removal of entity
             erase_fields: true           # set to false if you have non-nullable fields for mapping
-            delete_on_update: true       # determine wheter to delete the file upon update of entity
+            delete_on_update: true       # determine whether to delete the file upon update of entity
             inject_on_load: false        # determine whether to inject a File instance upon load
             namer_keep_extension: false  # force namers to keep original file extension
                                          # WARNING: Always validate file extensions when set to true to prevent security risks!

docs/directory_namer/howto/create_a_custom_directory_namer.md

@@ -23,4 +23,4 @@ vich_uploader:
 ## That was it!
 
 Check out the docs for information on how to use the bundle! [Return to the
-index.](/docs/index.md)
+index.](../../index.md)

docs/events/howto/remove_files_asynchronously.md

@@ -116,4 +116,4 @@ class RemoveFileEventSubscriber implements EventSubscriberInterface
 
 ## That was it!
 
-Check out the docs for information on how to use the bundle! [Return to the index.](/docs/index.md)
+Check out the docs for information on how to use the bundle! [Return to the index.](../../index.md)

docs/file_namer/howto/create_a_custom_file_namer.md

@@ -7,8 +7,6 @@ free to get any information from it to create the name, or inject any other
 service you require.
 
 > [!NOTE]
-> The `name` method in the interface accepts only objects, but your namer should accept both
-> objects and arrays. The interface method signature will be fixed in the next major version.
 > The name returned should include the file extension as well. This can easily
 > be retrieved from the `UploadedFile` instance using the `getExtension` or `guessExtension`
 > depending on what version of PHP you are running.
@@ -22,12 +20,12 @@ Here's a simple example:
 
 namespace App\Naming;
 
-use Vich\UploaderBundle\Mapping\PropertyMapping;
+use Vich\UploaderBundle\Mapping\PropertyMappingInterface;
 use Vich\UploaderBundle\Naming\NamerInterface;
 
 class MyNamer implements NamerInterface
 {
-    public function name(object|array $object, PropertyMapping $mapping): string
+    public function name(object|array $object, PropertyMappingInterface $mapping): string
     {
         $file = $mapping->getFile($object);
         $originalName = $file->getClientOriginalName();
@@ -48,7 +46,7 @@ implement the `Vich\UploaderBundle\Naming\ConfigurableInterface`:
 
 namespace App\Naming;
 
-use Vich\UploaderBundle\Mapping\PropertyMapping;
+use Vich\UploaderBundle\Mapping\PropertyMappingInterface;
 use Vich\UploaderBundle\Naming\ConfigurableInterface;
 use Vich\UploaderBundle\Naming\NamerInterface;
 
@@ -65,7 +63,7 @@ class MyConfigurableNamer implements NamerInterface, ConfigurableInterface
         $this->prefix = $options['prefix'] ?? $this->prefix;
     }
 
-    public function name(object|array $object, PropertyMapping $mapping): string
+    public function name(object|array $object, PropertyMappingInterface $mapping): string
     {
         $file = $mapping->getFile($object);
         $extension = $this->getExtensionWithOption($file, $this->keepExtension);
@@ -107,4 +105,4 @@ Where `App\Naming\MyNamer` is the configured service class.
 ## That was it!
 
 Check out the docs for information on how to use the bundle! [Return to the
-index.](/docs/index.md)
+index.](../../index.md)

docs/symfony_support_policy.md

@@ -19,4 +19,4 @@ You can also check [supported versions of PHP](//php.net/supported-versions.php)
 ## That was it!
 
 Check out the docs for information on how to use the bundle! [Return to the
-index.](/docs/index.md)
+index.](index.md)