Merge pull request #1482 from garak/fix-docs

📝 discourage annotations in the docs

composer.json

@@ -59,7 +59,6 @@
         "yoast/phpunit-polyfills": "^2.0"
     },
     "suggest": {
-        "doctrine/annotations": "If you use doctrine/doctrine-bundle >2.7, this package is required to use annotations",
         "doctrine/doctrine-bundle": "For integration with Doctrine",
         "doctrine/mongodb-odm-bundle": "For integration with Doctrine ODM",
         "doctrine/orm": "For integration with Doctrine ORM",

docs/configuration_reference.md

@@ -12,7 +12,7 @@ vich_uploader:
     metadata:
         auto_detection: true
         cache: file
-        type: attribute    # or annotation
+        type: attribute
     mappings:
         products:
             uri_prefix: /uploads    # uri prefix to resource

docs/known_issues.md

@@ -133,9 +133,9 @@ metadata is joined with the file during the upload.
 To summarize, [Gaufrette support for metadata is flawed](https://github.com/KnpLabs/Gaufrette/issues/108)
 (see issue [GH-163](https://github.com/dustin10/VichUploaderBundle/issues/163)).
 
-## Doctrine/annotations package required when using doctrine-bundle >= 2.8
+## Doctrine/annotations package required when using annotations and doctrine-bundle >= 2.8
 
-If your project is using `doctrine-bundle:>=2.8`, you must require `doctrine/annotations` package from
-your project as it is not required in `doctrine-bundle` anymore from this version.  
-This bundle is using a `Reader` interface from this package in order to work for both annotations
-and attributes mapping.
+If your project uses annotations and `doctrine-bundle:>=2.8`, you must require the `doctrine/annotations`
+package from your project, as it is not required in `doctrine-bundle` anymore from this version.  
+This bundle uses a `Reader` interface from this package in order to work for both attributes and annotations
+mapping, but annotations are deprecated and will be removed in the future.

docs/usage.md

@@ -153,100 +153,11 @@ class Product
 }
 ```
 
-Or, with annotations :
-
-``` php
-<?php
-
-namespace App\Entity;
-
-use Doctrine\ORM\Mapping as ORM;
-use Symfony\Component\HttpFoundation\File\File;
-use Vich\UploaderBundle\Mapping\Annotation as Vich;
-
-/**
- * @ORM\Entity
- * @Vich\Uploadable
- */
-class Product
-{
-    /**
-     * @ORM\Id
-     * @ORM\Column()
-     * @ORM\GeneratedValue(strategy="AUTO")
-     */
-    private ?int $id = null;
-
-    // ... other fields
-
-    /**
-     * NOTE: This is not a mapped field of entity metadata, just a simple property.
-     *
-     * @Vich\UploadableField(mapping="products", fileNameProperty="imageName", size="imageSize")
-     */
-    private ?File $imageFile;
-
-    /**
-     * @ORM\Column(nullable="true")
-     */
-    private ?string $imageName = null;
-
-    /**
-     * @ORM\Column(nullable="true")
-     */
-    private ?int $imageSize = null;
-
-    /**
-     * @ORM\Column(nullable="true")
-     */
-    private ?\DateTimeImmutable $updatedAt = null;
-
-    /**
-     * If manually uploading a file (i.e. not using Symfony Form) ensure an instance
-     * of 'UploadedFile' is injected into this setter to trigger the update. If this
-     * bundle's configuration parameter 'inject_on_load' is set to 'true' this setter
-     * must be able to accept an instance of 'File' as the bundle will inject one here
-     * during Doctrine hydration.
-     *
-     * @param File|\Symfony\Component\HttpFoundation\File\UploadedFile|null $imageFile
-     */
-    public function setImageFile(?File $imageFile = null): void
-    {
-        $this->imageFile = $imageFile;
-
-        if (null !== $imageFile) {
-            // It is required that at least one field changes if you are using doctrine
-            // otherwise the event listeners won't be called and the file is lost
-            $this->updatedAt = new \DateTimeImmutable();
-        }
-    }
-
-    public function getImageFile(): ?File
-    {
-        return $this->imageFile;
-    }
-
-    public function setImageName(?string $imageName): void
-    {
-        $this->imageName = $imageName;
-    }
-
-    public function getImageName(): ?string
-    {
-        return $this->imageName;
-    }
-
-    public function setImageSize(?int $imageSize): void
-    {
-        $this->imageSize = $imageSize;
-    }
+**Note:**
 
-    public function getImageSize(): ?int
-    {
-        return $this->imageSize;
-    }
-}
-```
+> This bundle also supports annotations, but the attribute syntax is recommended.
+> If you look for examples about annotations mapping, please refer to an older
+> version of the documentation.
 
 Alternatively you can use `Vich\UploaderBundle\Entity\File` embeddable for storing file info in your ORM entity: