Merge branch '2.8' into 3.4

* 2.8:
  Added a tip about atPath() method
  Added the missing class imports
  Update upload_file.rst for handling FileException

Author: javiereguiluz

controller/upload_file.rst

@@ -100,6 +100,7 @@ Finally, you need to update the code of the controller that handles the form::
     namespace AppBundle\Controller;
 
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Component\HttpFoundation\File\Exception\FileException;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\Routing\Annotation\Route;
     use AppBundle\Entity\Product;
@@ -123,11 +124,15 @@ Finally, you need to update the code of the controller that handles the form::
 
                 $fileName = $this->generateUniqueFileName().'.'.$file->guessExtension();
 
-                // moves the file to the directory where brochures are stored
-                $file->move(
-                    $this->getParameter('brochures_directory'),
-                    $fileName
-                );
+                // Move the file to the directory where brochures are stored
+                try {
+                    $file->move(
+                        $this->getParameter('brochures_directory'),
+                        $fileName
+                    );
+                } catch (FileException $e) {
+                    // ... handle exception if something happens during file upload
+                }
 
                 // updates the 'brochure' property to store the PDF file name
                 // instead of its contents
@@ -214,6 +219,7 @@ logic to a separate service::
     // src/AppBundle/Service/FileUploader.php
     namespace AppBundle\Service;
 
+    use Symfony\Component\HttpFoundation\File\Exception\FileException;
     use Symfony\Component\HttpFoundation\File\UploadedFile;
 
     class FileUploader
@@ -229,7 +235,11 @@ logic to a separate service::
         {
             $fileName = md5(uniqid()).'.'.$file->guessExtension();
 
-            $file->move($this->getTargetDirectory(), $fileName);
+            try {
+                $file->move($this->getTargetDir(), $fileName);
+            } catch (FileException $e) {
+                // ... handle exception if something happens during file upload
+            }
 
             return $fileName;
         }

reference/forms/types/options/property_path.rst.inc

@@ -3,13 +3,10 @@ property_path
 
 **type**: ``any`` **default**: ``the field's name``
 
-Fields display a property value of the form's domain object by default.
-When the form is submitted, the submitted value is written back into the
-object.
-
-If you want to override the property that a field reads from and writes
-to, you can set the ``property_path`` option. Its default value is the field's
-name.
+By default form fields read from and write to the properties with the same names
+in the form's domain object. The ``property_path`` option lets you define which
+property a field reads from and writes to. The value of this option can be any
+:doc:`valid PropertyAccess syntax </components/property_access>`.
 
 If you wish the field to be ignored when reading or writing to the object
 you can set the ``property_path`` option to ``false``, but using

validation/custom_constraint.rst

@@ -196,6 +196,12 @@ With this, the validator ``validate()`` method gets an object as its first argum
         }
     }
 
+.. tip::
+
+    The ``atPath()`` method defines the property which the validation error is
+    associated to. Use any :doc:`valid PropertyAccess syntax </components/property_access>`
+    to define that property.
+
 Note that a class constraint validator is applied to the class itself, and
 not to the property: