Merge pull request #1555 from endelwar/deprecate-annotations

Deprecate Annotation namespace in favor of Attribute namespace

Author: garak

UPGRADE.md

@@ -1,11 +1,19 @@
 # Upgrading from v2.8 to v2.9
 
+## Deprecations
+
+* The `Vich\UploaderBundle\Mapping\Annotation` namespace is deprecated. Replace it with `Vich\UploaderBundle\Mapping\Attribute`;
+  The old namespace will be removed in version 3.0.
+* `AttributeReader` methods: replace `*Annotation()` with `*Attribute()` (e.g., `getClassAnnotation()` → `getClassAttribute()`).
+
+## New Features
+
 * New `namer_keep_extension` configuration option to force namers to preserve original file extension.
 * Custom namers using `namer_keep_extension: true` must implement `ConfigurableInterface`.
 
 # Upgrading from v2.7 to v2.8
 
-* Namers are not public anymore. If you uses a custom namer, you can now make it private.
+* Namers are not public anymore. If you use a custom namer, you can now make it private.
 
 # Upgrading from v2.6 to v2.7
 
@@ -36,7 +44,7 @@
 
 * every class marked as `@final` is now final
 * all properties are now fully type-hinted
-* all methods arguments are now fully type-hinted
+* all method arguments are now fully type-hinted
 * all methods have now return types
 * all constructors now use property promotion
 * all deprecated features were removed

config/mapping.php

@@ -8,6 +8,7 @@
 use Metadata\MetadataFactory;
 use Vich\UploaderBundle\Metadata\CacheWarmer;
 use Vich\UploaderBundle\Metadata\Driver\AnnotationDriver;
+use Vich\UploaderBundle\Metadata\Driver\AttributeDriver;
 use Vich\UploaderBundle\Metadata\Driver\AttributeReader;
 use Vich\UploaderBundle\Metadata\Driver\XmlDriver;
 use Vich\UploaderBundle\Metadata\Driver\YamlDriver;
@@ -27,10 +28,15 @@
     $services->set('vich_uploader.metadata.attribute_reader', AttributeReader::class);
 
     // drivers
-    $services->set('vich_uploader.metadata_driver.annotation', AnnotationDriver::class)
+    $services->set('vich_uploader.metadata_driver.attribute', AttributeDriver::class)
         ->arg('$reader', service('vich_uploader.metadata.reader'))
         ->arg('$managerRegistryList', null); // replaced by compiler pass
 
+    $services->set('vich_uploader.metadata_driver.annotation', AnnotationDriver::class)
+        ->arg('$reader', service('vich_uploader.metadata.reader'))
+        ->arg('$managerRegistryList', null) // replaced by compiler pass
+        ->deprecate('vich/uploader-bundle', '2.9', 'The "%service_id%" service is deprecated, use "vich_uploader.metadata_driver.attribute" instead.');
+
     $services->set('vich_uploader.metadata_driver.xml', XmlDriver::class)
         ->args([
             service('vich_uploader.metadata.file_locator'),

docs/known_issues.md

@@ -73,7 +73,7 @@ namespace App\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
-use Vich\UploaderBundle\Mapping\Annotation as Vich;
+use Vich\UploaderBundle\Mapping\Attribute as Vich;
 
 #[ORM\Entity]
 #[Vich\Uploadable]

docs/usage.md

@@ -83,7 +83,7 @@ namespace App\Entity;
 
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
-use Vich\UploaderBundle\Mapping\Annotation as Vich;
+use Vich\UploaderBundle\Mapping\Attribute as Vich;
 
 #[ORM\Entity]
 #[Vich\Uploadable]
@@ -173,7 +173,7 @@ namespace App\Entity;
 use Doctrine\ORM\Mapping as ORM;
 use Symfony\Component\HttpFoundation\File\File;
 use Vich\UploaderBundle\Entity\File as EmbeddedFile;
-use Vich\UploaderBundle\Mapping\Annotation as Vich;
+use Vich\UploaderBundle\Mapping\Attribute as Vich;
 
 #[ORM\Entity]
 #[Vich\Uploadable]

docs/validators/file_required.md

@@ -6,7 +6,7 @@ It validates that either an existing file is present or a new file has been uplo
 ## Basic Usage
 
 ```php
-use Vich\UploaderBundle\Mapping\Annotation as Vich;
+use Vich\UploaderBundle\Mapping\Attribute as Vich;
 use Vich\UploaderBundle\Validator\Constraints as VichAssert;
 
 #[Vich\Uploadable]

src/DependencyInjection/Compiler/RegisterMappingDriversPass.php

@@ -30,7 +30,12 @@ public function process(ContainerBuilder $container): void
         }
 
         if (\count($managers) > 0) {
-            $drivers[] = $container->getDefinition('vich_uploader.metadata_driver.annotation')
+            // Support both new 'attribute' service and deprecated 'annotation' service
+            $driverServiceId = $container->hasDefinition('vich_uploader.metadata_driver.attribute')
+                ? 'vich_uploader.metadata_driver.attribute'
+                : 'vich_uploader.metadata_driver.annotation';
+
+            $drivers[] = $container->getDefinition($driverServiceId)
                 ->replaceArgument('$managerRegistryList', $managers);
         }
 

src/DependencyInjection/VichUploaderExtension.php

@@ -56,7 +56,7 @@ public function load(array $configs, ContainerBuilder $container): void
 
         $this->loadServicesFiles($container, $config);
         $this->registerMetadataDirectories($container, $config);
-        $this->registerAnnotationStrategy($container, $config);
+        $this->registerAttributeStrategy($container, $config);
         $this->registerCacheStrategy($container, $config);
 
         $this->registerListeners($container, $config);
@@ -139,9 +139,9 @@ protected function registerMetadataDirectories(ContainerBuilder $container, arra
         ;
     }
 
-    protected function registerAnnotationStrategy(ContainerBuilder $container, array $config): void
+    protected function registerAttributeStrategy(ContainerBuilder $container, array $config): void
     {
-        if (!$container->has('vich_uploader.metadata_driver.annotation')) {
+        if (!$container->has('vich_uploader.metadata_driver.attribute') && !$container->has('vich_uploader.metadata_driver.annotation')) {
             return;
         }
 
@@ -168,6 +168,16 @@ protected function registerAnnotationStrategy(ContainerBuilder $container, array
         }
     }
 
+    /**
+     * @deprecated since 2.9, use registerAttributeStrategy() instead
+     */
+    protected function registerAnnotationStrategy(ContainerBuilder $container, array $config): void
+    {
+        trigger_deprecation('vich/uploader-bundle', '2.9', 'Method "%s" is deprecated, use "registerAttributeStrategy()" instead.', __METHOD__);
+
+        $this->registerAttributeStrategy($container, $config);
+    }
+
     protected function registerCacheStrategy(ContainerBuilder $container, array $config): void
     {
         if ('none' === $config['metadata']['cache']) {

src/Mapping/Annotation/Uploadable.php

@@ -12,9 +12,15 @@
  * @Target({"CLASS"})
  * @NamedArgumentConstructor
  *
+ * @deprecated since 2.9, use Vich\UploaderBundle\Mapping\Attribute\Uploadable instead
+ *
  * @author Dustin Dobervich <ddobervich@gmail.com>
  */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class Uploadable implements AnnotationInterface
 {
+    public function __construct()
+    {
+        trigger_deprecation('vich/uploader-bundle', '2.9', 'The "Vich\UploaderBundle\Mapping\Annotation\Uploadable" class is deprecated, use "Vich\UploaderBundle\Mapping\Attribute\Uploadable" instead.');
+    }
 }

src/Mapping/Annotation/UploadableField.php

@@ -12,14 +12,13 @@
  * @Target({"PROPERTY"})
  * @NamedArgumentConstructor
  *
+ * @deprecated since 2.9, use Vich\UploaderBundle\Mapping\Attribute\UploadableField instead
+ *
  * @author Dustin Dobervich <ddobervich@gmail.com>
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY)]
 final class UploadableField implements AnnotationInterface
 {
-    /**
-     * Constructs a new instance of UploadableField.
-     */
     public function __construct(
         private readonly string $mapping,
         private readonly ?string $fileNameProperty = null,
@@ -28,6 +27,7 @@ public function __construct(
         private readonly ?string $originalName = null,
         private readonly ?string $dimensions = null
     ) {
+        trigger_deprecation('vich/uploader-bundle', '2.9', 'The "Vich\UploaderBundle\Mapping\Annotation\UploadableField" class is deprecated, use "Vich\UploaderBundle\Mapping\Attribute\UploadableField" instead.');
     }
 
     /**

src/Mapping/AnnotationInterface.php

@@ -2,6 +2,9 @@
 
 namespace Vich\UploaderBundle\Mapping;
 
-interface AnnotationInterface
+/**
+ * @deprecated since 2.9, use AttributeInterface instead
+ */
+interface AnnotationInterface extends AttributeInterface
 {
 }