[RFC] Doc update: Make Product getters and setters explicit

Resources/doc/known_issues.md

@@ -41,3 +41,50 @@ See issue [GH-123](https://github.com/dustin10/VichUploaderBundle/issues/123)
 When Propel is the chosen database driver, the "uploadable" entities must be
 known when the service container is built. As there is no way to retrieve all
 annotated entities, the only workaround is to define mappings using Yaml or XML.
+
+## No Upload is triggered when manually injecting an instance of Symfony\Component\HttpFoundation\File\File
+
+An upload will only be triggered if an instance of `Symfony\Component\HttpFoundation\File\UploadedFile`
+is injected into the setter for the `Vich\UploadableField` property of your class. Normally this is done 
+automatically if using Symfony Form but if your application logic is attempting to do this manually and you
+inject an instance of `Symfony\Component\HttpFoundation\File\File` *instead* the bundle will silently ignore
+your attempted upload.
+Consider the following class:
+
+``` php
+<?php
+/**
+ * @ORM\Entity
+ * @Vich\Uploadable
+ */
+class Product
+{
+    /**
+     * @Vich\UploadableField(mapping="product_image", fileNameProperty="imageName")
+     *
+     * @var \Symfony\Component\HttpFoundation\File\File $image
+     */
+    protected $image;
+
+    /**
+     * 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 \Symfony\Component\HttpFoundation\File\File $image
+     */
+    public function setImage(File $image)
+    {
+        $this->image = $image
+    }
+}
+```
+
+If the bundle's configuration parameter `inject_on_load` is set to `true` the `Product::setImage()` 
+method above must take an instance of `File` as when this class is hydrated by Doctrine this 
+bundle will automatically inject an instance of `File` there. However if you were to change 
+the image path to a new image in that instance of `File` and attempted a `flush()` nothing 
+would happen, instead inject a new instance of `UploadedFile` with the new path to your new 
+image to sucessfully trigger the upload.

Resources/doc/usage.md

@@ -196,6 +196,44 @@ class Product
      * @var string $imageName
      */
     protected $imageName;
+
+    /**
+     * 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 $image
+     */
+    public function setImage(File $image)
+    {
+        $this->image = $image
+    }
+
+    /**
+     * @return File
+     */
+    public function getImage()
+    {
+        return $this->image;
+    }
+
+    /**
+     * @param string $imageName
+     */
+    public function setImageName($imageName)
+    {
+        $this->imageName = $imageName;
+    }
+
+    /**
+     * @return string
+     */
+    public function getImageName()
+    {
+        return $this->imageName;
+    }
 }
 ```